| name | error-recovery-escalation |
| description | 5-level error recovery escalation: retry, nudge, replan, fallback, force-done — each with entry criteria and timeout before escalating |
| version | 1.0.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Bash","TaskUpdate","TaskList","TaskGet"] |
| agents | ["developer","qa","master-orchestrator","planner","devops-troubleshooter"] |
| category | Validation & Quality |
| tags | ["error-recovery","escalation","retry","resilience","agent-safety","recovery"] |
| best_practices | ["Always enter at the correct level based on error classification","Record every escalation in task metadata for reflection scoring","Force-done at level 5 emits partial results — never silent failure","Timeout between levels prevents infinite escalation loops"] |
| error_handling | ["If error type is ambiguous, default to level 2 (nudge)","If a level's timeout expires with no progress, escalate immediately","If level 5 is reached and still no output, emit empty partial result with explanation"] |
| source | builtin |
| trust_score | 100 |
| provenance_sha | cc29dc31711a102f |
Error Recovery Escalation
Purpose
Provide a structured, 5-level escalation ladder for recovering from agent errors. Each level has specific entry criteria, an action, and a timeout before escalating to the next level.
Level 1: RETRY — Same action, transient error
Level 2: NUDGE — Adjust parameters, same approach
Level 3: REPLAN — New approach, same goal
Level 4: FALLBACK — Different agent or model
Level 5: FORCE-DONE — Partial results with explanation
When to Invoke
Skill({ skill: 'error-recovery-escalation' });
Invoke when:
- An agent action fails with an error
- A judge-verification FAIL verdict is received
- A behavioral loop is detected (complement to
behavioral-loop-detection)
- A task has been in_progress longer than expected
- A tool call returns unexpected output
Iron Laws
- Always enter at the correct level — do not skip to level 3 for a transient network error
- Respect timeouts — if a level times out, escalate immediately regardless of progress
- Record every escalation — every level transition must be logged in task metadata
- Force-done is not failure — partial results with explanation are valid outcomes
- Level 5 always emits output — silent failure is never acceptable
Escalation Ladder
Level 1: RETRY
Entry criteria:
- Transient error: network timeout, rate limit, temporary unavailability
- Error is idempotent (repeating the exact same call is safe)
- Less than 3 retries have occurred for this action
Action:
- Wait for backoff period (1s, 2s, 4s — exponential)
- Retry the identical action unchanged
Timeout: 3 attempts × backoff = max ~30 seconds total
Escalate to Level 2 when: 3 retries exhausted without success
Example:
Read('.claude/context/data/index.db') → ENOENT
→ Level 1: Retry 3 times with 1s backoff
→ Still fails → escalate to Level 2
Level 2: NUDGE
Entry criteria:
