systematic-debugging

# Systematic Debugging Skill

> **Core Principle**: No fixes without root cause investigation first.

## The 3+ Fix Rule

> [!CRITICAL]
> If you have attempted 3 or more fixes without success, STOP.
> This indicates an architectural problem, not an isolated bug.
> Escalate to user with analysis.

---

## Four Phases

### Phase 1: Investigate

Before attempting ANY fix:

| Action | Purpose |
|--------|---------|
| Read error messages completely | Errors tell you what's wrong |
| Reproduce the issue | Confirm you're fixing the right thing |
| Check recent changes | What changed before it broke? |
| Trace data flow | Follow the data from input to error |
| Gather diagnostic evidence | Logs, stack traces, state dumps |

**Output**: Clear statement of what's happening and where

### Phase 2: Analyze

Compare broken state to working state:

| Action | Purpose |
|--------|---------|
| Find working examples | What does correct behavior look like? |
| Compare differences | What's different between working and broken? |
| Check assumptions | What are you assuming that might be wrong? |
| Review dependencies | What does this code depend on? |

**Output**: List of differences between working and broken states

### Phase 3: Hypothesize

Form a specific, testable hypothesis:

| Good Hypothesis | Bad Hypothesis |
|-----------------|----------------|
| "The null check on line 42 doesn't handle undefined" | "Something's wrong with the data" |
| "The API returns 404 when ID contains spaces" | "The API is broken" |
| "State updates before render completes" | "It's a timing issue" |

**Test minimally**: Change ONE thing to test the hypothesis

**Output**: Specific hypothesis with test plan

### Phase 4: Implement

Only after phases 1-3:

1. Write failing test that demonstrates the bug
2. Implement single fix addressing root cause
3. Verify fix works
4. Verify no regressions (run full test suite)

**Output**: Fix with evidence it works

---

## Red Flags: Restart the Process

If you cat