How to Debug Anything: A Method That Beats Guessing
A repeatable debugging method — reproduce, isolate, form a hypothesis, change one thing, verify — that finds root causes fast instead of poking at symptoms until something works.
The short answer: debug by method, not by vibes — reliably reproduce the bug, isolate where it happens, form one falsifiable hypothesis, change exactly one thing, and verify. The engineers who seem to find bugs "by magic" are just running this loop faster and skipping the guessing.
The difference between a developer who fixes a bug in ten minutes and one who flails for two hours is almost never knowledge of the codebase. It's method. Flailing looks like changing three things at once, reloading, and hoping. A method looks like a loop you run deliberately until the bug has nowhere left to hide. Here's the loop I run, and teach.
1. Reproduce it reliably first
You cannot fix what you can't reproduce, and you can't verify a fix against a bug that only shows up sometimes. Before touching any code, get it failing on demand: the exact steps, the exact input, the exact environment. If it's intermittent, that is the first clue — intermittency almost always means timing, ordering, caching, or shared state. A reliable repro is also your test oracle later: it's how you'll know you actually fixed it rather than disturbed it.
2. Read the actual error — all of it
The number of hours lost to not reading the stack trace is staggering. The error message and the top few frames usually name the file, the line, and the shape of the problem. Read it out loud if you have to. "Cannot read property 'name' of undefined" is not a mystery — something you expected to be an object is undefined, and the trace tells you where.
3. Isolate: binary-search the problem space
This is the highest-leverage move. The bug lives somewhere between "input is correct" and "output is wrong." Cut that space in half: log or breakpoint at the midpoint and ask is the value still correct here? If yes, the bug is downstream; if no, upstream. Repeat. A bug hiding in 2,000 lines is found in about 11 checks this way, versus reading all 2,000.
4. Form a hypothesis you can falsify
"Something's wrong with the discount" is not a hypothesis — you can't test it. "applyDiscounts double-counts the loyalty discount when the user is also in a campaign" is. State what you believe is happening in a way that a single experiment can prove false. If your hypothesis is vague, your next step will be too.
5. Change exactly one thing, then verify
The cardinal rule. Change one variable, re-run your repro, observe. If you change three things and it works, you've learned nothing — you don't know which change mattered, and you may have introduced two new bugs that happen to cancel out. One change, one observation. When the repro now passes and you understand why, you're done — and "I understand why" is the real finish line, not "it works now."
When you're truly stuck
- Rubber-duck it. Explain the problem aloud, line by line, to a person or an object. The bug often reveals itself in the telling, because explaining forces you to check assumptions you'd been skipping.
- Check your assumptions explicitly. The bug is almost always in the thing you're sure is fine. Log it anyway. "This is definitely getting called" — is it?
git bisect. If it worked last week, bisect the commits. It turns "which of 200 commits broke this" into about 8 checks.- Walk away. The shower insight is real. A stuck brain is pattern-matching on the wrong frame; stepping away resets it.
The mindset underneath
Debugging isn't about being clever; it's about being systematic when everything in you wants to guess. Every bug has a cause, that cause is knowable, and the loop above finds it. Replace "let me try changing this" with "let me find out where the value stops being correct," and you stop being at the mercy of the bug. That shift — from poking to investigating — is the whole skill.
