error-recovery

# Error Recovery Skill

> **Core Principle**: Classify before retry.

## When to Invoke

- Network timeout or connection failure
- API rate limit exceeded
- Intermittent test failure
- External service unavailable
- Resource temporarily locked
- Any transient error condition

---

## Error Classification

First, classify the error type:

| Type | Description | Default Action |
|------|-------------|----------------|
| **Transient** | Temporary, likely to resolve | Retry with backoff |
| **Permanent** | Won't resolve on retry | Fail immediately |
| **Degradable** | Can proceed without | Graceful degradation |
| **Unknown** | Can't classify | Limited retry, then escalate |

### Transient Errors

```
- Network timeout
- Connection reset
- 429 Too Many Requests
- 503 Service Unavailable
- 504 Gateway Timeout
- Lock contention
- Temporary file access
```

### Permanent Errors

```
- 400 Bad Request (invalid input)
- 401 Unauthorized (wrong credentials)
- 403 Forbidden (permission denied)
- 404 Not Found (resource doesn't exist)
- Syntax error in code
- Invalid configuration
```

### Degradable Errors

```
- Optional dependency unavailable
- Non-critical API failure
- Caching service down
- Logging service failure
```

---

## Retry Strategies

### Strategy: Immediate Retry

For: Quick transient errors (network glitch)

```
Attempts: 1
Delay: 0
```

### Strategy: Linear Backoff

For: Rate limits with known cooldown

```
Attempts: 3
Delays: 1s, 2s, 3s
```

### Strategy: Exponential Backoff

For: Unknown transient errors

```
Attempts: 4
Delays: 1s, 2s, 4s, 8s
Max delay: 30s
```

### Strategy: Exponential with Jitter

For: Multiple concurrent requests

```
Attempts: 4
Delays: random(0.5x, 1.5x) * base
Base: 1s, 2s, 4s, 8s
```

---

## Recovery Protocol

### Step 1: Classify Error

```
1. Read full error message
2. Check error code/type
3. Classify as: transient | permanent | degradable | unknown
4. If permanent → fail immediately
5. If degradable → attempt graceful degradat