Error Recovery Intelligence

Maintain a project-level error→solution mapping to avoid rediscovering known problems.

File Location

known-issues.md at the project root (same level as package.json, Cargo.toml, etc.).

When to Consult

Before starting any debugging investigation:

1. Check if known-issues.md exists.
2. Search it for the error message, error code, or failing test name.
3. If a match is found, try the documented solution first before full investigation.

When to Update

After resolving a bug that is likely to recur:

• Environment-dependent errors (missing services, port conflicts, env vars)
• Configuration errors (wrong versions, missing dependencies, build flags)
• Test failures caused by external state (database needs seeding, service needs starting)
• Platform-specific issues (Windows vs. Unix path handling, line endings)
• Errors that took significant investigation to diagnose

Do NOT record:

• One-off logic bugs (the fix is in the code; the commit message has the context)
• Errors already documented in the project's README or docs
• Transient network/API failures

Entry Format

Each entry must be concise and actionable:

## [Short description]

**Error:** `exact error message or pattern`
**Cause:** One sentence explaining why this happens.
**Fix:**
```bash
exact command or steps to resolve

Context: When this typically occurs (e.g., "after fresh clone", "on Windows", "when DB is not running").

## File Management

- Keep `known-issues.md` under 50 entries. If it grows beyond that, prune entries that haven't been relevant in months.
- Group entries by category (Environment, Dependencies, Tests, Build, Platform).
- **When an issue is fixed, strike the heading — do not delete the entry.** Change `## Some error` to `## ~~Some error~~ ✅ Fixed in vX.Y.Z` and leave the body in place.

  The session-start hook and the keyword-recall hook both skip headings that begin with `## ~~`, so a struck entry costs nothing at injection time while remaining greppable. Deleting it throws away the diagnosis — and a "fixed" error that regresses is exactly the case where the old root-cause analysis is worth most. Delete only when the entire subsystem the entry describes no longer exists.

## Integration

- `systematic-debugging` consults this file in Phase 1 (Investigate) before generating hypotheses.
- `using-superpowers` reads this file during the entry sequence when it exists.
- After resolving a debugging session, offer to add the error→solution mapping if it meets the "When to Update" criteria.