A Field Guide to Debugging
Watch a great debugger work and it looks like intuition — they glance at a stack trace, mutter something, and fix the bug in minutes. It isn't intuition. It's a method, applied so many times it looks effortless. The method is learnable, and this is the version I teach every engineer I mentor.
Reproduce it first
Nothing else matters until you can make the bug happen on demand. A bug you can reproduce is an experiment; a bug you can't is a rumor. Shrink the reproduction relentlessly — fewer steps, less data, smaller inputs — because every step you remove eliminates a suspect. Half the time, the act of shrinking the repro reveals the cause by itself.
Make one guess at a time
The failure mode I see most is shotgun debugging: change four things, rerun, and — when the bug disappears — learn nothing. Which change fixed it? Was it even one of them, or the restart? Discipline looks slower and is dramatically faster:
- Form one hypothesis about the cause
- Design the smallest test that would prove it wrong
- Run it, and actually believe the result
That last point is real: the most common debugging mistake is dismissing evidence that contradicts the theory you've grown fond of. The bug doesn't care what you believe.
Binary search the universe
When you have no good hypothesis, split the search space in half. Does the bad data exist before this function or after it? Comment out half the pipeline. Does the old build work? git bisect will find the guilty commit in a dozen steps even across a thousand commits. Halving is humble — it admits you don't know where the bug is — and it's the fastest known way to find out.
Read the error message
It sounds insulting. It isn't. Under pressure, everyone — including twenty-year veterans — pattern-matches the first line of an error and stops reading. The answer is astonishingly often in line four: the actual file, the actual column, the mention that the certificate expired yesterday. Read the whole thing, out loud if you're stuck. Then read the line above it.
Keep a log of your worst bugs
The bugs that take days deserve a postmortem paragraph: what it was, why it hid so long, what would have caught it sooner. Reread that file twice a year. Debugging skill is mostly a library of scars — the log just makes sure you keep the library after the scars fade.