debug-systematic

Systematic Debugging Protocol

A disciplined, evidence-based approach to debugging that prevents guessing and ensures root cause discovery.

The 4-Phase Protocol

Phase 1: REPRODUCE (Establish Ground Truth)

Goal: Create reliable reproduction steps before ANY investigation.

Actions:

1. Document exact steps to trigger the bug
2. Record environment specifics (OS, versions, config, memory, network)
3. Determine frequency: Always? Sometimes? Specific conditions?
4. Capture exact error messages, stack traces, screenshots
5. Test on different environments to isolate variables

Key Questions:

• When did it last work correctly?
• What changed since then? (code, deps, config, infrastructure)
• Is it environment-specific?
• Is it data-specific?
• Is it timing-specific?

Output: Clear reproduction steps that reliably trigger the issue.

---

Phase 2: ISOLATE (Narrow the Scope)

Goal: Reduce the search space from "entire codebase" to "specific component."

Techniques:

Binary Search:

1. Identify two points: working state and broken state
2. Test the midpoint
3. Recurse into the broken half
4. Continue until the change is identified

Git Bisect (for regressions):

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Git will checkout commits for testing
# After each test:
git bisect good  # or git bisect bad
# Continue until culprit found

Code Elimination:

• Comment out sections to isolate the problem
• Create minimal reproduction case
• Strip away everything non-essential

Environment Isolation:

• Test in isolation (unit test the failing path)
• Compare working vs broken environments
• Use fresh installs to eliminate pollution

Output: "The bug is in [specific component/function/line range]"

---

Phase 3: DIAGNOSE (Understand Root Cause)

Goal: Know exactly WHY the bug occurs, not just WHERE.

Scientific Method:

1. Observe: What exactly is happening?
2. Hypothesize: Why might this be happening?
3. Predict: If hypothesis is correct, what else would be true?
4. Test: Verify predictions with evidence
5. Iterate: Refine hypothesis based on results