systematic-debugging

Systematic Debugging

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Never apply symptom-focused patches that mask underlying problems. Understand WHY something fails before writing a single line of fix code.

The Four-Phase Framework

Phase 1: Reproduce & Gather Evidence

Before touching any code:

1. Read the full error — every word matters, including the stack trace
2. Reproduce consistently — define exact steps. If you can't reproduce, you can't verify a fix
3. Check recent changes — git log --oneline -10, what changed before this broke?
4. Gather diagnostics — console output, network tab, React DevTools, state snapshots
5. Define expected vs actual — write it down explicitly

# Find the breaking change
git log --oneline -20
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>

Phase 2: Trace to Root Cause

Follow the data, not your assumptions:

1. Where does the error appear? (symptom location)
2. What value is wrong at that point?
3. Where does that value come from? (trace upstream)
4. Is the value wrong at the source, or corrupted in transit?
5. What assumption was violated?

Key insight: The bug is rarely where the error appears. Trace upstream until you find where correct data becomes incorrect.

Phase 3: Hypothesize & Test

Scientific method, not shotgun debugging:

1. One clear hypothesis — "The error occurs because X causes Y"
2. Predict the outcome — "If my hypothesis is correct, then Z should happen when I..."
3. Change ONE variable — isolate the test
4. Observe result — did it match prediction?
5. Iterate or proceed — revise hypothesis if wrong, implement if right

Phase 4: Fix & Verify

1. Write a failing test that captures the exact bug
2. Implement the fix — address root cause, not symptoms
3. Verify the test passes
4. Run full test suite — no regressions
5. Verify in browser — test the actual user flow