oimiragieo/error-recovery-escalation

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:

• Action failed 3 times at Level 1 (retry exhausted)
• Error suggests wrong parameters (wrong path, wrong key, malformed input)
• Judge-verification FAIL with evidenceOfCompletion < 8 (no artifacts found)

Action:

• Adjust parameters: different path, different key, simplified input
• Keep same overall approach and goal
• Try 2-3 variants

Timeout: 5 minutes total for all nudge variants Escalate to Level 3 when: All nudge variants fail or timeout expires

Example:

Write('output/result.json', ...) → EPERM
→ Level 2: Try .claude/context/tmp/result.json, then /tmp/result.json
→ All fail → escalate to Level 3

---

Level 3: REPLAN

Entry criteria:

• Level 2 nudges exhausted or timed out
• Judge-verification FAIL with goalAlignment < 15 (wrong approach)
• Behavioral loop detected at REPLAN threshold (≥3 similar actions)
• Architectural blocker requiring different approach

Action:

• Abandon current approach entirely
• Spawn planner agent or invoke plan-generator skill for a new plan
• Document old approach as a known-bad path in task metadata

Timeout: 15 minutes for new plan + initial execution Escalate to Level 4 when: Replan also fails, or planner cannot produce a viable plan

Example:

Auth middleware implementation fails repeatedly
→ Level 3: Replan with different auth library (passport → jose)
→ New plan also fails due to dependency conflict → escalate to Level 4

---

Level 4: FALLBACK

Entry criteria:

• Level 3 replan exhausted or timed out
• Current agent type is inappropriate for the task
• Different model tier may improve outcome (haiku → sonnet → opus)
• Behavioral loop detected at EXPLORE threshold (≥5 similar actions)

Action:

• Switch agent type (e.g., developer → devops-troubleshooter)
• OR escalate model tier (haiku → sonnet, or sonnet → opus)
• Provide full context of what was tried and why it failed
• Pass accumulated error context as explicit input

Timeout: 20 minutes for fallback agent execution Escalate to Level 5 when: Fallback agent also fails or timeout expires

Example:

Developer agent cannot resolve platform-specific build error
→ Level 4: Spawn devops-troubleshooter with full error log
→ Still unresolved after 20min → escalate to Level 5

---

Level 5: FORCE-DONE

Entry criteria:

• Level 4 fallback exhausted or timed out
• Behavioral loop detected at FORCE-DONE threshold (≥8 similar actions)
• Total escalation time exceeds session budget
• External blocker (service down, missing credentials, unavailable resource)

Action:

• Emit partial results — whatever was completed successfully
• Write detailed explanation of what failed and why
• Call TaskUpdate with { partial: true, escalationLevel: 5, explanation: '...' }
• Recommend follow-up actions for human resolution

Output contract:

{
  "status": "partial",
  "completedSteps": ["step1", "step2"],
  "failedAt": "step3",
  "failureReason": "<specific error>",
  "escalationPath": [1, 2, 3, 4, 5],
  "recommendation": "<what a human should do to finish>"
}

Example:

External API service is down
→ Level 5: Emit partial results (all non-API steps completed)
→ TaskUpdate with partial: true, explanation of API outage
→ Recommend retry when service is restored

---

Error Classification Matrix

| Error Type | Entry Level | Rationale | | ------------------------------ | ---------------------- | ------------------------------- | | Network timeout | 1 (retry) | Transient, safe to retry | | Rate limit | 1 (retry with backoff) | Transient, wait and retry | | File not found | 2 (nudge) | Wrong path, try alternatives | | Permission denied | 2 (nudge) | Wrong path/permissions | | Wrong output format | 2 (nudge) | Adjust input parameters | | Goal misalignment (judge FAIL) | 3 (replan) | Need different approach | | Agent capability mismatch | 4 (fallback) | Need different agent | | External service down | 5 (force-done) | Cannot resolve programmatically | | Missing credentials | 5 (force-done) | Requires human intervention |

---

TaskUpdate Protocol

Every level transition MUST be recorded:

// On entering a level
TaskUpdate({
  taskId: '<task-id>',
  status: 'in_progress',
  metadata: {
    recoveryLevel: <1-5>,
    recoveryAction: 'retry|nudge|replan|fallback|force-done',
    errorType: '<classification>',
    previousLevels: [<completed levels>],
    enteredAt: new Date().toISOString(),
  }
});

// On Level 5 completion
TaskUpdate({
  taskId: '<task-id>',
  status: 'completed',
  metadata: {
    partial: true,
    escalationLevel: 5,
    escalationPath: [1, 2, 3, 4, 5],
    completedSteps: ['<step1>', '<step2>'],
    failedAt: '<step>',
    failureReason: '<specific error>',
    recommendation: '<human follow-up action>',
    summary: 'Force-done: partial results emitted after 5-level escalation',
  }
});

---

Integration Points

| Skill | Relationship | | -------------------------------- | ---------------------------------------------------------------------- | | behavioral-loop-detection | Feeds escalation triggers (REPLAN at 3, EXPLORE at 5, FORCE-DONE at 8) | | judge-verification | FAIL verdict triggers escalation at appropriate level | | plan-generator | Called at Level 3 (replan) to produce new approach | | verification-before-completion | Gates completion before escalation is declared unnecessary | | debugging | Provides root cause analysis before Level 3 escalation |

---

Enforcement Hooks

Input validated against schemas/input.schema.json before execution. Output contract defined in schemas/output.schema.json.

Pre-execution hook: hooks/pre-execute.cjs Post-execution hook: hooks/post-execute.cjs (emits observability event)

---

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md for known error patterns in this codebase. Check .claude/context/memory/issues.md for known blockers.

After completing:

• Level 5 reached → Append to .claude/context/memory/issues.md with root cause
• New error classification discovered → Append to .claude/context/memory/learnings.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.