debugging

Debugging — hypothesis testing, not patch roulette

Debugging is a science experiment, not a repair job. You form a theory of what's wrong, make the one change that theory predicts will alter the outcome, and observe. Most debugging time is wasted by skipping that discipline: patching where the error appeared instead of where it originated, changing three things at once, or trying fixes in a loop and keeping the wreckage of the ones that failed. The rules below are the difference between an hour and a day — and between a fix and a fix-shaped bug.

How to apply this

Run the loop in order: reproduce (for a production report, pull the real event first — section 2 feeds section 1) → read → locate → hypothesize → test the hypothesis → fix → prove. Don't skip ahead to "fix" — a fix you can't connect to a confirmed cause is a guess with good posture.

And stop the line. When something unexpected breaks mid-task, this loop preempts the feature work — don't push past a failing test or broken build to keep building. Errors compound: an unfixed bug in step 3 makes steps 4–6 wrong, and the wreckage multiplies the diagnosis.

And know what isn't a defect. A system that is slow but correct hasn't failed, and running this loop at it produces hypotheses no reproduction can settle — that is [[performance]], which borrows the one-change rule below and adds the baseline that decides whether a change was worth keeping.

1. Reproduce it first — no reproduction, no fix

You cannot verify a fix for something you cannot make happen. Before theorizing, make the failure occur on demand: the exact command, input, and state that triggers it. Then shrink it — smallest input, fewest steps — because every element you remove is a suspect eliminated.

If you can't reproduce it, that's not a dead end; reproducing it is now the task — and it has moves, bucketed by what varies. Timing-dependent? Add timestamps around the suspect area, widen the race window with artificial delays (sleep/setTimeout at the suspected interleaving point), run under load or concurrency to raise the collision probability. Environment-dependent? Diff runtime versions, env vars, and data state (an empty vs. populated database changes whole code paths); try reproducing in CI, where the environment is clean. State-dependent? Run the failing scenario in isolation versus after other operations — a difference means leaked state; hunt globals, singletons, shared caches (a failing test gets this first: run it alone to rule out test pollution). Truly random? Log defensively at the suspected site, alert on the exact error signature, write down the observed conditions, and revisit on recurrence — that's a plan, not a shrug. A "fix" shipped against an unreproduced bug is a coin flip you can't even watch land.