debug

``` ██████╗ ███████╗██████╗ ██╗ ██╗ ██████╗ ██╔══██╗██╔════╝██╔══██╗██║ ██║██╔════╝ ██║ ██║█████╗ ██████╔╝██║ ██║██║ ███╗ ██║ ██║██╔══╝ ██╔══██╗██║ ██║██║ ██║ ██████╔╝███████╗██████╔╝╚██████╔╝╚██████╔╝ ╚═════╝ ╚══════╝╚═════╝ ╚═════╝ ╚═════╝ ``` # Debug to root cause ## The Iron Law **No fix without a root-cause investigation first.** A patch applied to a symptom you don't understand usually moves the bug rather than removing it. ## The feedback loop IS the skill Everything else is mechanical. Your first job is a **fast, deterministic pass/fail signal** for the bug. Build the best one you can afford, preferring higher rungs: 1. A failing automated test that reproduces it (best — becomes your regression test) 2. A one-shot command: `curl`, a CLI invocation, a script with a snapshot diff 3. A tiny harness that exercises the path 4. Manual reproduction with logged output (last resort) A 2-second deterministic loop is a debugging superpower; invest in it before theorizing. If you can't reproduce it, that's the bug to solve first. (Prefer the earliest rung you can manage — 1 is best.) ## Hypotheses: plural and falsifiable Don't anchor on the first idea. Write **3-5 ranked hypotheses**, each with a *prediction* you can test ("if it's a caching issue, then clearing the cache fixes it; if it's a race, then adding a delay changes the outcome"). Instrument to *discriminate* between them, not just to confirm a favorite. Tag every diagnostic probe you add with a marker like `[DEBUG-a4f2]` so cleanup at the end is a single grep — never leave instrumentation behind. ## The 3-fixes rule If you've tried **3 fixes and the problem keeps reappearing somewhere new, STOP.** Do not attempt fix #4. Cascading symptom-fixes mean your mental model of the architecture is wrong — discard the current hypotheses and re-derive them against the *structure*, not the symptom. (Your human's tells — "stop guessing", "ultrathink this", "why does this keep happening" — are the same signal: restart at root cause.) ## Name the cause before you fix Before writing any fix, state it in one sentence: **this symptom is caused by X, via mechanism Y.** If you can't, you haven't found the root cause — keep instrumenting. The fix must target X, not the place the symptom surfaced. ## Performance and flaky bugs use a different loop - **Performance regressions:** measure, don't theorize. Capture a quantified baseline and a target delta, **profile** to find the real hot path, and use `git bisect` to find the commit that introduced it. "Feels slow" is not a signal; a number before/after is. - **Flaky / non-deterministic bugs:** there's no 2-second deterministic signal yet, so *manufacture* one — run the case N times and measure the failure rate, then force it to reproduce reliably (loop the test, inject delays, fix the seed, enable a race detector) before fixing. A fix you can't show drives the failure rate to 0 over N runs is not verified. ## Close the loop Once you've found and fixed the root cause, the reproducing test becomes a **permanent regression test** (hand to `forge:tdd` if it isn't already a test). Remove all `[DEBUG-]` probes. Then `forge:verify` with the now-green test as evidence.