My Error Recovery

Error Recovery

Graceful failure handling, retry patterns, and strategic pivots.

⚡ Quick Start

Tool failed or command errored? → 1. Read the error carefully — stderr often contains the real cause → 2. Classify: transient, permanent, or user-correctable? → 3. Apply the appropriate recovery pattern → 4. Never silently ignore errors

Error Classification

Recovery Patterns

Pattern 1: Retry with Backoff (Transient)

For network timeouts, rate limits, temporary failures:

Attempt 1 → fails (timeout)
  → Wait 2s → Attempt 2
    → fails (timeout)
      → Wait 4s → Attempt 3
        → succeeds or escalate

Max 3 attempts. If still failing, classify as permanent.

Pattern 2: Fix and Retry (Agent-Correctable)

For wrong paths, wrong tools, wrong syntax:

1. Read error message carefully
2. Identify what was wrong
3. Fix the approach
4. Retry immediately (no user ask)

Example: read failed because file doesn't exist → check path, maybe find first, then read correct path.

Pattern 3: Escalate to User (User-Correctable)

For missing dependencies, auth issues, branch conflicts:

1. Explain what failed and why
2. Provide the exact command/fix needed
3. Ask user to apply it, then retry

Example: npm install fails because Node.js version mismatch → tell user exact version needed.

Pattern 4: Pivot Strategy (Permanent / Ambiguous)

When the approach itself is wrong:

1. Acknowledge the failure
2. Propose 2-3 alternative approaches
3. Let user choose or ask for clarification

Example: web_scrape fails because site blocks bots → propose web_extract, ctx_fetch_and_index, or ask for URL alternative.

3-Strikes Circuit Breaker

Track failures per (tool + target) pair across the session:

Mandatory Pivot Options (Strike 3 fails)

1. Switch tool category — bash → read, edit → write, read → ctx_execute_file
2. Decompose task — break into smaller steps, retry a sub-step
3. Escalate to user — explain the repeated failure, ask for guidance
4. Delegate to subagent — if parallelism helps, use @skills/pi-subagents

When to reset the strike counter

• Reset when the tool succeeds on the same target
• Reset when you switch to a different tool for the same target
• Reset when the target changes (different file, different URL)
• Do NOT reset when retrying with slightly different parameters — that's Strike 2

Rationale: Prevents retry loops that generate 100+ errors in a single session. A failure after 3 attempts means the approach is wrong, not the parameters.

HTTP-Specific Recovery

Tool-Specific Recovery

Bash (command errors)

• Check stderr first — stdout may be empty but stderr has the cause
• Common: command not found → check if tool is installed
• Common: permission denied → check file permissions or use sudo
• Common: No such file or directory → verify path with ls or find

Edit (file mutations)

• oldText must match exactly — whitespace matters
• If edit fails, re-read the file to get current exact content
• Never guess — always re-read before retrying edit

Read (file access)

• File doesn't exist → find or ls to locate it
• Permission denied → check with ls -la
• Binary file → use ctx_execute_file instead

Write (new files)

• Directory doesn't exist → mkdir -p first
• Overwriting existing → confirm with user unless explicitly told to overwrite

Common Mistakes

❌ Wrong: Silently retrying the exact same failed command ✅ Right: Read error, fix root cause, then retry

❌ Wrong: Asking user "what should I do?" without diagnosing first ✅ Right: Diagnose, classify, then ask with specific options or fix

❌ Wrong: Treating a permanent error as transient and retrying 5 times ✅ Right: 3 retries max for transient, then escalate or pivot. Use the 3-Strikes rule.

❌ Wrong: Retrying the same failed bash command 4+ times with minor tweaks ✅ Right: After 3 strikes on the same (tool + target), pivot strategy. The approach is wrong.

❌ Wrong: Ignoring stderr and assuming command succeeded ✅ Right: Always check stderr, especially for bash commands

❌ Wrong: Giving up after first failure without attempting recovery ✅ Right: Every error is recoverable with the right classification

Related Skills

• @skills/my-workflow — Session boundaries when errors require context switch
• @skills/my-session-retrospective — Log errors for skill improvement
• @skills/my-project-lifecycle — Plan phase error prevention

Versioning

• Last updated: 2026-05-26
• Version: 1.1
• Update notes: Added 3-Strikes Circuit Breaker per (tool + target) to prevent 100+ error loops. Strike 3 mandates pivoting strategy (switch tool, decompose, ask user, or delegate) rather than retrying indefinitely.