systematic-debugging

Systematic Debugging

ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

When to Use

• Encountering bugs or test failures
• Unexpected behavior in code
• Before proposing any fix

The Four Phases

Phase 1: Root Cause Investigation

Before proposing any solution:

1. Read error messages thoroughly - Don't skip warnings or stack traces; they often contain exact solutions
2. Reproduce consistently - Verify you can trigger the issue reliably with documented steps
3. Check recent changes - Examine git diff, dependencies, and configuration modifications
4. Gather diagnostic evidence - In multi-component systems, add instrumentation at component boundaries
5. Trace data flow - Backward trace from the error to find where bad values originate

Phase 2: Pattern Analysis

Establish the pattern before fixing:

1. Locate similar working code in the codebase
2. Read reference implementations completely (not skimmed)
3. List every difference between working and broken code
4. Understand all dependencies and assumptions

Phase 3: Hypothesis Testing

Apply scientific method:

1. State your hypothesis clearly: "I believe X is failing because Y, evidenced by Z"
2. Test with the smallest possible change
3. Change only ONE variable at a time
4. Verify results before proceeding

Phase 4: Implementation

Fix the root cause systematically:

1. Create a failing test case first (TDD)
2. Implement a single fix addressing only the root cause
3. Verify the fix resolves the issue without breaking other tests
4. If fix doesn't work, return to Phase 1

Red Flags - STOP Immediately

• Proposing fixes without understanding the issue
• Attempting multiple simultaneous changes
• Assuming problems without verification
• Skipping evidence gathering
• Making "quick fixes" before investigation

When 3+ Fixes Fail

STOP. This signals an architectural problem, not a fixable bug:

1. Do not attempt another fix
2. Return to Phase 1
3. Question whether the underlying pattern/design is sound
4. Ask: "Should we refactor architecture vs. continue fixing symptoms?"

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

Results

Systematic approach: 15-30 minutes to resolution with 95% first-time success vs. Trial-and-error: 2-3 hours of thrashing with 40% success and new bugs introduced