Systematic Debugging

A structured four-phase process for diagnosing software bugs: Reproduce → Isolate → Hypothesize → Verify. Prevents guessing and ensures you find the root cause, not just a workaround.

When to Use

• User reports a bug or unexpected behavior without an obvious cause
• An error message appears but the source is unclear
• A fix was applied but the problem persists
• Tests are failing intermittently (flaky tests)
• Production behavior differs from local behavior

How to Use

Phase 1: Reproduce reliably

A bug you can reproduce consistently is halfway solved.

1. Get the exact error message, stack trace, and environment
2. Identify exact steps to trigger the bug
3. Confirm the bug happens in a clean environment (not just local state)
4. Record: OS, runtime version, dependencies, config values
5. Try: does it fail on every run, or only sometimes?

If intermittent: add timing, logging, or retry logic to isolate the trigger.

Phase 2: Isolate the failure

Narrow the failure to the smallest possible unit.

1. Add logging before/after suspected areas to find where state diverges
2. Binary search through code: comment out half, does it still fail?
3. Check: when did this last work? (git log, git bisect)
4. Check: what changed recently? (git diff main, dependency updates)
5. Reproduce in a minimal test case, strip away all unrelated code

# git bisect to find the breaking commit
git bisect start
git bisect bad                  # current commit is broken
git bisect good v2.0.0          # last known good tag
# git will checkout commits, test each, then:
git bisect good   # or
git bisect bad
# Repeat until git identifies the culprit commit
git bisect reset

Phase 3: Generate hypotheses

Form 2-3 specific, testable hypotheses about the root cause.