How I Debug Bugs Systematically — Reproduce, Instrument, Fix, Harden

Bug fixes that stick aren't lucky guesses — they follow a repeatable workflow. Here's the four-step process I use on every debug engagement, from "my app keeps crashing" to "the login is broken sometimes."

Most "fixes" I see fail the same way: someone changes a line of code, the symptom goes away, and three weeks later the same bug shows up in a slightly different form. That's not a fix — that's whack-a-mole.

Real bug fixes follow a repeatable workflow. Whether the symptom is "the app crashes on the checkout screen," "the API returns wrong data sometimes," or "login fails for some users but not others," the four steps are the same.

Step 1 — Reproduce It

You can't fix what you can't reproduce. If a bug is intermittent, your first job is to make it stop being intermittent.

What that looks like in practice:

Get the exact device, browser, OS, account, and timing from the user who reported it
Try to replicate on your own machine — same browser version, same data, same network conditions
If it only happens "sometimes," start logging what's different between the runs that fail and the runs that pass

A bug you can reproduce in 30 seconds is one you can probably fix in a day. A bug you can't reproduce can take weeks of guessing.

Step 2 — Instrument It (Add Debug Logs)

Once you can reproduce, you need visibility into what's actually happening — not what you assume is happening.

Add debug logs at the boundaries:

Where data enters the system (API requests, form submissions, file uploads)
Where decisions are made (if/else branches, validation, auth checks)
Where data leaves (database writes, API responses, UI renders)

The goal isn't to log everything — it's to log enough to confirm or rule out each hypothesis. Most production bugs come down to "the data isn't what I thought it was at line X" or "this code path isn't executing when I thought it was." Debug logs at the right spots answer both in minutes.

Step 3 — Fix the Underlying Cause

This is where most fixes go wrong. The temptation is to patch the symptom — wrap the crash in a try/catch, add a null check, return a default value — without understanding *why* the bug happened.

A real fix answers:

What was the actual cause? (Not the symptom — the cause.)
Why did the code allow this state in the first place?
What other places in the code could have the same issue?

Sometimes the fix is a one-line change. Sometimes it's a refactor that prevents the whole class of bug. The difference is whether you understood the cause or just made the error message stop appearing.

Step 4 — Harden It (Prevent Regression)

A bug fix that has no test is a bug waiting to come back. The last step is to write the smallest reasonable test that would catch this exact issue if it ever recurred.

For a logic bug: a unit test that pins the expected behavior with the input that previously failed
For a UI bug: an integration test that walks the user flow that previously crashed
For an API bug: a test that hits the endpoint with the payload that previously misbehaved

This isn't about hitting 100% test coverage. It's about ensuring this specific bug never silently returns. Three months from now when someone refactors that code, the test will catch the regression in CI instead of in production.

The 80/20 of This Workflow

For most small bugs, the time split is:

50% reproducing
25% instrumenting
15% writing the fix
10% adding the test

If you're spending 80% of your time on the fix, you're guessing. Slow down on reproducing and instrumenting — the fix usually writes itself once you understand the cause.

When This Workflow Pays Off Most

This approach especially shines when:

The bug is intermittent or "only happens sometimes"
You're working on a codebase you didn't write
The previous developer is no longer available
The bug has been "fixed" before and keeps coming back
The cost of regression is high (billing, auth, data integrity)

For trivial typos or obvious syntax errors, you can skip straight to the fix. For anything that took the user more than 30 seconds to describe, run the full workflow.

---

Got a bug that's been eating your team's time? I take on these exact engagements: I'll reproduce, instrument, fix the cause, and add a regression test. Most one-issue bug fixes are a $1,500 Quick Win — one concrete deliverable, working in production, in about a week. Bigger or stacked issues fit a $500 Discovery where I'd audit the codebase and lay out a roadmap.