# My Error Recovery

> **ALWAYS use when:** a tool fails, a command errors, a request times out, a file read returns nothing unexpected, or something goes wrong during execution. Use when the user says "it failed", "error", "something went wrong", "that didn't work", or when any tool call returns an error, stderr, or non-zero exit code. Also use when a skill produces unexpected output, a provider is unavailable, or the agent needs to pivot strategy after a failure. **DO NOT use for:** code review of error-prone code — use @skills/my-code-review. Preventing errors through planning — use @skills/my-project-lifecycle.

- Skill: `alexleekt/my-error-recovery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alexleekt/my-error-recovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexleekt/my-error-recovery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alexleekt (https://skillmd.com/u/alexleekt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexleekt/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

| Type | Characteristics | Recovery |
|------|----------------|----------|
| **Transient** | Network timeout, rate limit, temporary unavailability | Retry with backoff |
| **Permanent** | Syntax error, missing file, wrong path, logic bug | Fix root cause |
| **User-correctable** | Missing dependency, wrong branch, need auth | Ask user with specific fix |
| **Agent-correctable** | Wrong tool used, wrong file path, wrong syntax | Fix and retry immediately |

## 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:

| Strike | Action |
|--------|--------|
| **Strike 1** | Retry with identical parameters (transient flake). Log the error. |
| **Strike 2** | Retry with adjusted parameters (path fix, longer timeout, different syntax). |
| **Strike 3** | Final retry. If still failing → **mandatory pivot**. |
| **Strike 4+** | **STOP.** Do not retry the same operation again. |

### 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

| Status | Meaning | Recovery |
|--------|---------|----------|
| 429 | Rate limited | Retry with exponential backoff |
| 503 | Service unavailable | Retry once, then report |
| 404 | Not found | Check URL, fix path |
| 401/403 | Auth denied | Escalate to user |
| 500+ | Server error | Retry once, then report |
| Timeout | No response | Retry with longer timeout |

## 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.