systematic-debugging

Systematic Debugging

Core Principle

Find root cause before fixes. Symptom patches create new bugs and hide the actual failure.

IRON LAW

No fixes before root-cause investigation.

Four Phases

1. Reproduce and read: capture the exact error, stack, failing command, route, input, or user action. Read the full output.
2. Trace and compare: inspect recent diffs, working examples, data flow, configuration, and boundaries.
3. Hypothesize: state one root-cause hypothesis with evidence. Test one variable at a time.
4. Fix and verify: write a failing test or minimal repro when possible, implement one fix, run verification.

Stop Conditions

• If you cannot reproduce, gather more data instead of guessing.
• If two fixes fail, pause and re-investigate.
• If three fixes fail, question the architecture and ask before continuing.
• If the issue touches multiple systems, instrument each boundary before changing code.

Red Flags

• “Quick fix for now.”
• Multiple changes before testing.
• Proposing solutions before tracing the failure.
• Increasing timeouts without proving timing is the root cause.
• Fixing the place that crashed instead of where bad data originated.

Output Contract

## Symptom
## Reproduction
## Evidence Gathered
## Root Cause Hypothesis
## Fix Plan
## Verification Evidence