error-recovery-escalation

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

1. Always enter at the correct level — do not skip to level 3 for a transient network error
2. Respect timeouts — if a level times out, escalate immediately regardless of progress
3. Record every escalation — every level transition must be logged in task metadata
4. Force-done is not failure — partial results with explanation are valid outcomes
5. 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: