superstack-debuglisted

# superstack-debug A bug is a wrong **belief**, not just a wrong line. Fix your model of the system first; the code change then falls out. Never debug by mutation — "change something, rerun, hope" burns evidence and moves the bug around. ## The procedure 1. **Reproduce first.** Get the minimal command that shows it red, and run it. A failure you can't trigger on demand can't be verified fixed — and if you can't reproduce it, *that is the finding*: report it and instrument (logging, a capture) instead of shipping a speculative patch. 2. **State the contradiction in one sentence.** "X should produce Y because Z; it produces W." If you can't fill in Z, you don't understand the intended behavior yet — go read the source of truth first (R1). 3. **Run a hypothesis ledger, cheapest-first.** List 2–5 candidate causes. Each gets a designed probe with a **predicted outcome written down before running it** — a probe whose outcome you can't predict is a coin flip, not an experiment. One variable per probe. Strike out falsified rows in writing; that's what prevents circling back to a cause you already killed. 4. **Bisect the delta when a working/broken pair exists** — version, commit, input, environment, config. Differential evidence beats staring at code. 5. **Three strikes → up a level.** The same category of fix failing twice means the shared assumption underneath is wrong (R2). Stop patching; re-read the contradiction; widen the frame. 6. **Fix the invariant, not the instance.** Ro