Recover autonomously from failures. Diagnose before retrying — blind retries waste tokens and amplify mistakes.
Recovery Decision Tree
Error detected
├── Transient? (network, rate limit, timeout)
│ └── → Retry with exponential backoff (max 3×)
├── Tool failure? (bad args, wrong schema)
│ └── → Fix args, retry once; if still fails → escalate
├── Logic error? (wrong output, assertion failure)
│ └── → Diagnose root cause → apply fix → verify → continue
├── Context overflow?
│ └── → Compress context → resume from last checkpoint
└── Unknown?
└── → Log state, pause, surface to human
Retry Rules
- Transient (HTTP 5xx, rate limit 429, network timeout): retry after 1s, 4s, 16s — then fail
- Deterministic (validation error, type mismatch): fix the root cause first — retrying without a fix wastes budget
- Max retries: 3 per error type per phase; consecutive failures in same phase → escalate tier or stop
Checkpoint Pattern
Before any risky operation, save state so recovery can resume:
.agents/plans/.loop-state.json
{
"phase": "implement",
"step": 3,
"lastSuccess": "tests green on auth module",
"pendingFiles": ["src/api/users.ts"],
"checkpoint": "<ISO timestamp>"
}
On failure, reload checkpoint and skip completed steps — do not repeat work.
Diagnose Before Fixing
Never patch without understanding:
- Read the full error — stack trace, exit code, stderr
- Reproduce in isolation (smallest failing case)
- Form one hypothesis — what is wrong and why?
- Test the hypothesis with a targeted check (log, assertion, type check)
- Fix exactly what the evidence shows
- Verify the fix resolves the error AND does not break adjacent tests
Context Overflow Recovery
When context is exhausted mid-task:
- Summarize completed work → 3–5 bullet points
- Save summary + checkpoint to
.agents/plans/recovery-<timestamp>.md - Start a fresh context with the summary as preamble
- Resume from the last saved checkpoint
Escalation Ladder
| Attempt | Action |
|---|---|
| 1 | Retry same tier |
| 2 | Switch model within tier |
| 3 | Escalate to next tier (haiku → sonnet → opus) |
| 4 | Pause — surface blocker to human with full context |
What NOT to Auto-Heal
- Hard blocks:
rm -rf, schema drops, force push to main - Security failures: don't lower validation to make tests pass
- Ambiguous requirements: if the spec is unclear, ask — don't guess and continue
Output
Self-Heal Report
────────────────
Error: <original failure>
Diagnosis: <root cause>
Action: <what was done>
Attempts: <N>
Outcome: RESOLVED | ESCALATED | BLOCKED
Resumed: <from checkpoint / from scratch>