Systematic Debugging

---
name: systematic-debugging
description: Four-phase root cause investigation before attempting fixes. Use when debugging bugs, test failures, or unexpected behavior.
---

# 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