Debug Like a System, Not a Hunt

Debugging looks like magic until you watch someone who is good at it: they do not guess, they narrow. The process is the same every time — reproduce reliably, isolate the smallest case, form one hypothesis, verify it — and it works whether the bug is a typo or a race condition.

Step 1: Reproduce it deterministically

"It fails sometimes" is useless. A repro is the smallest sequence of actions that produces the wrong behavior every time. Strip the environment down — one user, one record, one request — until the failure is a coin flip you can call. Without a reliable repro you are not debugging; you are hoping.

Step 2: Isolate the smallest case

Bisect. Delete half the inputs — if the bug persists, the cause was in the half you kept. Comment out half the code paths. This is the same binary search instinct as git bisect, applied at the code level: each test halves the suspect space.

Step 3: One hypothesis at a time

Form a single falsifiable statement — "the crash happens when user.preferences is null" — and test it. Do not chase two theories at once. The moment your hypothesis is confirmed, you know exactly what the fix must be; the moment it is disproved, you have eliminated a whole branch.

Step 4: Verify the fix, not the absence of the error

The test that proves the fix is the one that fails before the fix and passes after. If your "fix" makes the error go away without you understanding why, you have hidden the bug, not fixed it — it will come back.

Try it yourself — bisection in action, in JS

// The bug is in one of these. Isolate by elimination:
const suspects = ["parse()", "validate()", "save()", "notify()"];
// If the crash persists with parse+validate removed, the cause is downstream:
const remaining = suspects.slice(2);
console.log("suspects after bisection:", remaining); // ["save()", "notify()"]

The meta-rule

Never change two things at once. If the bug disappears and you do not know which change fixed it, you have learned nothing and the bug will return.