Debugging Methodically

Debugging is a search problem. The engineers who are fast at it are not guessing better — they are eliminating half the search space at a time instead of poking at whatever they touched last.

Reproduce first. A bug you cannot reproduce is a bug you cannot verify you fixed. Nail down the smallest reliable reproduction; that act alone often reveals the cause, because minimising forces you to identify which conditions actually matter.

Form a hypothesis you can falsify. "The cache is returning stale data" is testable. "Something is wrong with the cache" is not. Then design the cheapest test that splits the possibilities — check the value at the boundary between two components rather than tracing from the top.

Bisect. In the code path, in the data, or in history. git bisect finds the introducing commit in log₂(n) steps and is chronically underused; a hundred commits is seven checkouts.

Read the error properly. Whole stack trace, actual line numbers, actual values. An enormous share of debugging time is spent on a message that already said what was wrong.

Change one thing at a time. Changing three and seeing it work leaves you not knowing why, which means you have not fixed it — you have hidden it.

Question your assumptions last but genuinely. "That library can't be wrong", "that config is definitely applied", "that code path can't run" — when the evidence contradicts an assumption, verify it directly rather than reasoning around it.

Fix the cause, not the symptom. A null check that silences a crash without explaining why the value was null converts a loud bug into a quiet one, which is a downgrade.