fable-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. Root cause found → grep every caller and sibling path; the fix goes where all paths route through, or the siblings stay broken.
7. Verify red → green on the exact reproduction from step 1 — red before the fix, green after, at the layer of the claim (→ fable-verify). A fix you never watched fail isn't proven to be the fix.
8. Root-cause the escape. Always the second question: why did the existing checks miss this? Mint the runnable rule — the test/assert/check that would have caught it — and log the gotcha (trap → cause → rule) to .fable/project.md. If a task file is open in .fable/tasks/, record the decision trail there. And if the broken behavior was vouched for earlier, find that claim in .fable/claims-log — and in .fable/claims-log.<year>, where fable-ship archives older ones; a claim you can't find is not a claim that was never made — then mark it FALSIFIED <date> — <what actually broke>: a falsified Verified: is a calibration miss, and how the check missed it is the gotcha.

Red flags — you are debugging by mutation

• "Let me just try…" with no predicted outcome.
• Editing code before reproducing the failure.
• Two changes in one probe (you won't know which mattered).
• A fix explained with "somehow" or "must have been".
• Deleting or weakening the failing test to get green.
• Attempt three of the same fix.