Error Handler

---
name: error-handler
description: |
  Trigger when the user asks to improve error handling, add error boundaries,
  structure exceptions, or design retry logic. Phrases: "error handling",
  "error boundary", "exception strategy", "retry logic", "fail gracefully".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# Error Handler

Audit a codebase's error handling and apply consistent patterns. Distinguish
recoverable from unrecoverable errors; do not swallow failures.

## Prerequisites

- Codebase has at least basic logging or observability
- User has decided on a stance for unknown errors (fail fast vs log and continue)

## Steps

1. **Grep the codebase for error patterns:**
   - `catch (e)` blocks with no body - silent swallow, fix these
   - `console.error` without re-throw or escalation
   - `throw new Error("...")` without context
   - `any` catches in TypeScript

2. **Classify errors into four buckets:**
   - **Programmer errors** (null deref, type mismatch) - should crash loudly
     in dev, never be caught broadly
   - **Operational errors** (network timeout, rate limit) - should retry with
     backoff up to a cap, then escalate
   - **User errors** (invalid input) - should return a structured error
     response, not throw
   - **Contract errors** (upstream API breaks its schema) - should fail loud
     with full context; these are bugs in the integration

3. **Apply the right pattern per bucket:**

   User input validation at the boundary:
   ```ts
   const result = InputSchema.safeParse(req.body);
   if (!result.success) {
     return Response.json({ error: result.error.format() }, { status: 422 });
   }
   ```

   Operational retry with backoff:
   ```ts
   async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
     for (let i = 0; i < attempts; i++) {
       try { return await fn(); } catch (e) {
         if (i === attempts - 1) throw e;
         await new Promise(r => setTimeout(r, 2 ** i * 250));
       }
     }
     throw new Error("unreachable");
   }
   ```

   Context-preserving rethrow:
   ```ts
   try { await fetchUser(id); }
   catch (e) { throw new Error(`fetchUser failed for id=${id}: ${e}`); }
   ```

4. **Never use bare `try/catch/empty`.** If you catch, either log with context
   and rethrow, or deliberately handle. Silent swallows are bugs waiting to
   happen at 2am.

5. **Add an error boundary at the framework root** for React apps. In Next.js,
   `app/error.tsx` catches render-time errors.

## Output

- Grep report showing error-handling hotspots
- PR that fixes the silent-swallow and empty-catch cases first
- README section documenting the project's error-handling stance