diagnosing-bugs

# Diagnosing Bugs A discipline for hard bugs. Skip phases only when explicitly justified. When exploring the codebase, consult `.claude-code-hermit/compiled/` (hermit knowledge base — architecture decisions and codebase health assessments) to build a mental model of relevant modules before reading source. Check any ADRs in the area you're touching. Diagnostic byproducts (failing-test output, stack traces, repro snapshots, instrumentation logs) go in `.claude-code-hermit/raw/` — ephemeral inputs under analysis, not `.claude-code-hermit/compiled/`. Reusable lessons from the diagnosis go to auto-memory. ## 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 / payl...