> For the complete documentation index, see [llms.txt](https://docs.thecolliery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thecolliery.org/tools/canaries/skill-2.md).

# resilience-audit

Failure-mode audit (FMEA for software) — for each way the system can fail (network, storage, partial completion, crash, concurrency, bad input), check whether code DETECTS, HANDLES, RECOVERS, and COMM

For every operation: **"what happens when this FAILS?"** Report; do NOT fix unless asked.

## Failure categories

1. **External I/O** — network down/slow, API 4xx/5xx/timeout, rate-limit. Retry w/ backoff? Timeout set? Clear error vs hang?
2. **Storage** — disk full, permission denied, partial write. Atomic write (temp+rename)? Cleanup on failure? Existing good copy untouched?
3. **Partial completion** — half-done op (50/100 files). Reported as FAILURE, never success.
4. **Crash / OOM** — killed mid-op. Idempotent restart? No orphaned half-state?
5. **Concurrency** — two instances, race, deadlock. Locking / idempotency / safe re-entry?
6. **Input / data** — malformed, null, truncated, huge. Validate at boundary? Fail-fast?
7. **Dependency down** — fallback/cache/graceful degrade? Clear error vs silent hang?
8. **Resource exhaustion** — bounded? Backpressure? Cleanup on error path?

Per-stack timeout/atomicity/idempotency patterns to grep: read `references/checks.md` before scanning.

## For each failure point, check 4 things

* **Detected?** code notices it (doesn't swallow)?
* **Handled?** retry/fallback/fail-clean — not ignored, not silent-success?
* **Recoverable?** rollback/idempotent; no data loss or corruption?
* **Communicated?** clear error to user+log; not a hang, not a false "done"?

## Discipline

* Trace actual failure path (cite file:line). Don't assume handling exists; prove it.
* "partial = failure" — any path reporting success on partial completion = CRITICAL.
* "logged" ≠ "handled" — swallowed+logged error that corrupts state or returns success = CRITICAL.

## Fix mode (choice-gated)

After the report, present via `ask_question`:

* **Fix safe ones** — add missing timeout, null/input validation, clear error+log on unhandled path. Each: checkpoint → record a build+test BASELINE → fix → build+tests → revert only if a NEW failure appeared versus the baseline.
* **Let me pick** — user-selected fixes only.
* **Report only** — change nothing.

NEVER auto-fix: retry/rollback/recovery/atomicity logic (semantic changes can introduce new failure modes).

## Grants & denials (CLASSIFY-BLOCK)

| class | step it powers                                                                                        | grant                                             | on denial                                                                                  |
| ----- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| read  | trace failure paths for the 8 categories above                                                        | `Read`·`Grep`·`Glob`                              | refuse that file, name it — never a clean bill                                             |
| write | Fix mode's safe-guard apply, incl. checkpoint → baseline → build+tests → revert only on a NEW failure | `Edit`·`Bash` (checkpoint/build/revert need exec) | report the fix as NOT applied AND the checkpoint/revert as NOT available, never claim done |

## Output

`| operation | failure mode | effect | handling (file:line) | severity | recommended guard |` Ordering/atomicity findings · Summary (counts + top fixes) · Not assessed

Severity: CRITICAL (data loss/corruption/silent-success) · HIGH (crash/hang/partial-no-recovery) · MEDIUM (poor degradation/missing retry) · LOW (cosmetic)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thecolliery.org/tools/canaries/skill-2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.