Debugging Like a Detective, Not a Gambler
Hey, it's been a while since i wrote the last article. In this article i'm going to talk about Debugging—why some developers spend 6 hours stuck on a bug while another engineer walks over and finds it in 4 minutes.
Spoiler: the second engineer isn't psychic. They just aren't gambling.
Let's look at how most people debug when their code breaks.
The problem with "Shotgun Debugging"
Conventionally, nobody teaches us a systematic process for debugging in school. So when an error pops up, we panic and do what's called Shotgun Debugging:
See weird bug -> Guess a random fix -> Change 3 lines at once -> Re-run -> Still broken (or breaks in a new way) -> Add console.log("here 1") -> Repeat for 4 hours
There are huge problems with this approach:
- When you change 3 things at once without knowing why it broke, you aren't testing a hypothesis—you're pulling a slot machine lever.
- Even if the bug accidentally goes away, you have no idea why, and you probably just introduced a quieter bug somewhere else.
- You trust your assumptions ("oh,
user.idis definitely a string here, no need to check that") when the bug exists specifically because one of your assumptions is wrong!
In short, the problem is guessing before isolating. You are trying to fix a bug before you even know which half of the pipeline is lying to you.
It happened with me multiple times actually.
The Ghost Token Bug
A few months ago, i had an authentication flow that worked 100% fine on localhost, worked fine in staging, and failed randomly for about 20% of requests in production with 401 Invalid Signature.
For three hours, i gambled:
- "Maybe the JWT secret env variable has a trailing newline?" (Checked, no.)
- "Maybe clock drift between servers is expiring the token?" (Added
clockTolerance: 60, still failing.) - "Maybe CORS is stripping headers?" (Tweaked CORS middleware, nothing changed.)
I was exhausted and frustrated because nothing made sense.
Finally, i stopped changing code. I took a blank sheet on my tablet, drew the 6 steps the token goes through from login to verification, and asked: "At which exact boundary does a valid string turn into an invalid string?"
Instead of guessing fixes, i logged the exact SHA-256 hash and character length of the raw token string at Point A (Client creation) and Point D (Server middleware).
Boom. On the 20% of failing requests, the token contained a + character in its Base64 encoding, and one specific redirect URL was passing the token in a query parameter without encodeURIComponent(). The URL parser was silently turning every + into a space character ' '!
The moment i stopped guessing and used binary search to compare the input vs output across the boundary, the bug was dead in 10 minutes.
Other issues with emotional debugging
There are a few other traps that waste hours during debugging:
- Not reading the actual error message: Seeing a red wall of text, reading only the last line, and ignoring line 3 where the stack trace literally tells you
TypeError: Cannot read properties of undefined (reading 'address') at auth.ts:84. - Debugging without a reproducible case: Clicking through 8 UI screens manually every time you test a fix instead of capturing the failing payload as a
curlcommand or a 5-line test.
The unconventional way: Binary Search Debugging
When a detective walks into a crime scene, they don't arrest random people on the street. They lock down the room and eliminate half the suspects at a time:
Reproduce Reliably (In 1 Click) -> Map the Pipeline -> Cut the Pipeline in Half (Check Midpoint) -> Which Half is Broken? -> Cut That Half in Half -> Root Cause Found
Here is the Information Map of how Binary Search Debugging finds any bug in $O(\log n)$ steps:
[ Step 1: UI Input ] ---> [ Step 2: API Serialize ] ---> [ Step 3: Proxy/URL ] ---> [ Step 4: Auth Middleware ] ---> [ Step 5: DB ]
^
(Check Midpoint Here First!)
|
+-------------------------+-------------------------+
| |
Is data ALREADY corrupted at Step 3? Is data STILL clean at Step 3?
| |
v v
[ Bug is in Steps 1, 2, or 3 ] [ Bug is in Steps 4 or 5 ]
(Ignore Backend & DB completely!) (Ignore Frontend completely!)
Binary Search on a bug pipeline.
Instead of checking Step 1, then guessing at Step 5, then tweaking Step 2, you check the exact middle (Step 3). In one check, you just eliminated 50% of the entire system! Two more checks and there is literally nowhere left for the bug to hide.
Benefits of Binary Search Debugging
Now i don't think i need to tell you the benefits of this approach. But still:
- You turn an unpredictable 6-hour nightmare into a calm, 15-minute checklist.
- You never break working code by applying random "fixes" to the wrong layer.
- You can debug systems in languages you barely know, because inputs and outputs at boundaries never lie.
- Your blood pressure stays normal when production breaks.
- You always know why the fix worked.
A foolproof framework (The Detective Loop)
Next time you are stuck on a bug for more than 15 minutes, take your hands off the keyboard and follow these rules:
The core loop
- Read the entire error and stack trace out loud: Literally every word. Don't skim.
- Create a 2-second reproduction: Copy the failing network request as
cURLor a minimal test script so you can trigger the bug in 1 second without clicking the UI. - Question your proudest assumption: Write down "I am 100% sure X is true," and immediately verify X first. (Spoiler: half the time, X is false, or you're editing a file that isn't even running because you forgot to restart the container!)
- Bisect the data flow: Check the state of the data halfway between where it was last known to be good and where it blew up.
- Use
git bisectfor regressions: If it worked yesterday and is broken today across 30 commits, rungit bisectto let binary search find the exact commit that broke it in 5 steps. - Change ONE variable at a time: If your hypothesis doesn't work,
git checkout/ undo it immediately before trying the next hypothesis.
Tools
git bisect for finding breaking commits, Chrome DevTools (Copy as cURL), interactive debuggers / breakpoints, and a piece of paper to list hypotheses and cross them off.
When quick intuition still makes sense
If you get a typo error you've seen 50 times before and know the fix in 10 seconds, fix it and move on. The Detective Loop is for the moment your first quick guess fails. Once your first guess is wrong, stop gambling and start bisecting.
Final Words
That's it for the blog. Next time a bug makes you say "that's impossible, the computer is broken," remember: the computer is doing exactly what you told it to do. Cut the pipeline in half, check the midpoint, and find out where your mental model diverged from reality.
see you in the next one.
Further Reading
How to Use AI Without Becoming Brain-Dead
A framework for shipping 5x faster with LLMs without losing your engineering edge.
How to Read Large Codebases Without Losing Your Mind
A non-linear guide to jumping into 100,000+ lines of unfamiliar code.
Responses (0)
Share your thoughts, critique, or questions
No responses yet
Be the first to share your perspective or critique.