Menu
Use when encountering compile errors, test failures, runtime exceptions, or unexpected behavior during implementation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | error-recovery |
| description | Use when encountering compile errors, test failures, runtime exceptions, or unexpected behavior during implementation. |
| depends_on | ["test-and-fix-loop"] |
| commonly_followed_by | ["test-and-fix-loop","observability"] |
Use this skill when something goes wrong during implementation.
| Type | Examples | Priority |
|---|---|---|
| Compile / build error | Missing import, type mismatch, syntax error | Fix immediately |
| Test failure | Assertion failed, timeout, unexpected output | Fix immediately |
| Lint / static analysis | Unused variable, style violation | Fix before marking done |
| Runtime error | Panic, null pointer, unhandled exception | Fix immediately |
| Logic error | Wrong output, missing edge case | Investigate then fix |
The "3 attempts then escalate" rule counts same-family failures only. Cosmetic differences (line numbers, timestamps, memory addresses, stack depth) do not reset the counter — the underlying problem is the same.
Before retrying, save each attempt's raw error output to a temp file and call the reference detector:
bash harness/core/failure-family-detect.sh attempt-N.log attempt-N+1.log
# exit 0 → same family (do NOT reset counter)
# exit 1 → different family (reset counter, continue)
# exit 2 → unknown / empty input (treat as same family; do not reset)
The script classifies errors into 7 families (test_failure, lint,
build_error, exception, schema_error, auth_error, infra_error).
It is adapter-neutral — any runtime can shell out to it. If your runtime
cannot run shell scripts, emulate the classification natively and record
the result in failure_families[] on your trace (see
docs/schemas/trace.schema.yaml).
Record each attempt's family in the trace so reviewers can audit the escalation decision:
failure_families:
- attempt: 1
family: test_failure
same_as_previous: false
- attempt: 2
family: test_failure
same_as_previous: true
- attempt: 3
family: test_failure
same_as_previous: true # escalate
If 3 same-family fix attempts fail, report to the user:
Error: [exact error message]
File: [file:line]
Attempts:
1. [what you tried] → [result]
2. [what you tried] → [result]
3. [what you tried] → [result]
Hypothesis: [what you think the underlying issue is]
Suggested next step: [what a human should check]
// nolint, @SuppressWarnings, or equivalent without justification.any) to avoid a type error.All conditions below must be verifiable from task artifacts:
file:line).failure_families[] records the detected family per attempt and the same_as_previous flag.// nolint, catching and ignoring an exception) without resolving the root cause is a workaround, not a fix. Document it as such.Use for general product implementation work that is not primarily backend architecture, pure integration wiring, or screenshot-driven design-to-code.
Use when the main deliverable is maintainable documentation such as repository rules, onboarding guides, runbooks, ADRs, or architecture notes.
Use on first entry to a new repository to run environment scanning and ask targeted boundary questions before implementation.
Use after writing or modifying code to enforce the mandatory write → test → fix → repeat validation cycle.
Use before committing to a design or plan to force assumption-surfacing. The agent challenges your design, questions edge cases, and flags gaps — you patch vague decisions. Prevents the failure mode where a design "feels explained" but contains hidden flaws that only appear during implementation.
Use to establish and maintain a shared domain glossary (UBIQUITOUS_LANGUAGE.md). Creates a single source of term definitions that all agents, prompts, and documents must use — preventing semantic drift and repeated re-explanation across sessions.