diagnosing-bugslisted

# Diagnosing Bugs A discipline for hard bugs. Skip phases only when explicitly justified. ## Phase 0 — Search past learnings Search `docs/solutions/` (if the project has one) for learnings matching the symptom — the error message, the module, the failure mode. A past solution may short-circuit the whole diagnosis: when one matches, verify its root cause applies here before building anything, and carry its gotchas into the phases below. ## Phase 1 — Build a feedback loop **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.** ### Ways to construct one — try them in roughly this order 1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e. 2. **Curl / HTTP script** against a running dev server. 3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot. 4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network. 5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation. 6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps)