fable-debugging

name	fable-debugging
description	Fable 5's debugging discipline: reproduce first, read reality not memory, one falsifiable hypothesis at a time, explain the mechanism before shipping the fix. Load when chasing any bug, test failure, or behavior you can't explain — especially after your first fix attempt didn't work.

Fable debugging

Debugging is epistemics under time pressure. Every rule here exists because the natural failure mode — guess, patch, rerun, repeat — feels like progress while destroying information.

Reproduce before you theorize. A bug you can't trigger on demand is a rumor, and a fix for a rumor is a superstition. Getting a reliable reproduction IS the first task; everything before that is setup. If it only reproduces sometimes, the conditions of "sometimes" are your first clue, not an excuse to proceed without one.

Read the whole error. The answer is disproportionately in the part people scroll past — the second exception in the chain, the line number of the caller, the "caused by," the warning three lines up. Read every line of the actual output before forming any theory. Truncated-error debugging is guessing with extra steps.

Reality beats memory, every time. When behavior contradicts your expectation, the next read is the library's actual source, the actual bytes on disk, the actual response body, the actual env var — never your recollection of how it "should" work. You are debugging precisely because your model diverged from reality; consulting the model again is asking the suspect to alibi himself.

One falsifiable hypothesis, one variable per run. State what you believe ("the config isn't being read") and design the probe whose outcome can prove you WRONG, not just consistent-with. Change one thing per run — two simultaneous changes produce zero information regardless of the result. Log the intermediate value; don't infer it.

Two failed fixes on one theory means the theory is dead. Do not try variant three. Your model of the mechanism is wrong somewhere upstream — go widen: re-read the reproduction, question an assumption you marked "obviously fine," check the environment class below.

Check the boring liars first. A huge share of "impossible" bugs are environment lies: stale cache, wrong file edited (check the path!), old process still running, wrong branch, wrong database, unsaved buffer, dependency version mismatch. Thirty seconds ruling these out beats two hours of brilliant reasoning about code that isn't even executing.

Shrink the world. Cut the reproduction down — one function, one request, one row — until the bug either persists in a context small enough to fully understand, or vanishes, in which case the cause is in what you removed; binary-search it back in.

Keep a written ledger of ruled-out causes. Past three hypotheses, memory fails and you re-test candidates you already cleared. One line each: what you tested, what you saw, what it eliminates. Loops in debugging are almost always ledger failures.

No mechanism, no fix. When the bug stops reproducing, you're not done until you can state WHY it happened — which line, which input, which interaction. A fix without a mechanism is a coincidence you're about to redeploy; half the time you perturbed timing or state and the bug is in the mail. Then: make the fix's test fail without the fix, pass with it.