---
name: systematic-debugging
description: A disciplined 4-phase debugging framework that emphasizes identifying the root cause before applying fixes. Use when encountering any bug, test failure, unexpected behavior, or production issue. Prevents trial-and-error debugging and promotes deep understanding of issues.
triggers:
  - debug this
  - fix this bug
  - why is this failing
  - test failure
  - unexpected behavior
  - it's not working
  - error in production
  - build failure
---

# Systematic Debugging

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

Random fixes waste time and create new bugs. Quick patches mask underlying issues. If Phase 1 is not complete, no fix can be proposed.

## When to Use

Use for ANY technical issue: test failures, production bugs, unexpected behavior, performance problems, build failures, integration issues.

Use ESPECIALLY when under time pressure (emergencies make guessing tempting), when "just one quick fix" seems obvious, when previous fixes did not work, or when the issue is not fully understood.

## The Four Phases

### Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

**1. Read Error Messages Carefully**
- Do not skip past errors or warnings
- Read stack traces completely
- Note line numbers, file paths, error codes
- The error message often contains the exact solution

**2. Reproduce Consistently**
- Can you trigger it reliably?
- What are the exact steps?
- Does it happen every time?
- If not reproducible, gather more data — do not guess

**3. Check Recent Changes**
- What changed that could cause this?
- Git diff, recent commits
- New dependencies, config changes
- Environmental differences

**4. Gather Evidence in Multi-Component Systems**

When the system has multiple components, add diagnostic instrumentation BEFORE proposing fixes:

```
For EACH component boundary:
  - Log what data enters the component
  - Log what data exits the component
  - Compare expected vs actual at each boundary
  - The first boundary where expected != actual is your root cause location
```

**5. Form a Hypothesis**
- Based on evidence, what is the MOST LIKELY root cause?
- Can you explain WHY the bug occurs, not just WHERE?
- If you cannot explain the mechanism, you have not found root cause

### Phase 2: Minimal Fix

Once root cause is confirmed:

- Fix ONLY the root cause, nothing else
- Make the smallest possible change
- Do not refactor while fixing bugs
- Do not "improve" nearby code
- One fix, one commit

### Phase 3: Verification

After applying the fix:

- Reproduce the original bug scenario — confirm it is fixed
- Run the full test suite — confirm no regressions
- Test edge cases related to the fix
- If verification fails, return to Phase 1 (your root cause hypothesis was wrong)

### Phase 4: Prevention

After the fix is verified:

- Add a regression test that would have caught this bug
- Document what went wrong and why
- Consider if similar bugs could exist elsewhere
- Update monitoring or logging if the bug was hard to detect

## Anti-Patterns (NEVER DO)

| Anti-Pattern | Why It Fails |
|---|---|
| "Let me try this quick fix" | Skips root cause, creates new bugs |
| Changing multiple things at once | Cannot tell which change fixed it |
| "It works now" without understanding why | Bug will return |
| Fixing symptoms instead of cause | Masks the real issue |
| Assuming the obvious explanation | Confirmation bias |
| Reverting to "known good" without understanding | Loses learning |

## Debugging Decision Tree

```
Bug reported
  → Can you reproduce it?
    → No: Gather more data (logs, user steps, environment)
    → Yes: Read the error message carefully
      → Error message points to cause?
        → Yes: Verify hypothesis, then Phase 2
        → No: Check recent changes (git log, deploys)
          → Found suspicious change?
            → Yes: Test reverting it (locally)
            → No: Add instrumentation at component boundaries
              → Found where expected != actual?
                → Yes: You have root cause. Phase 2.
                → No: Widen investigation scope
```

## Output Format

When debugging, always report:

```
ROOT CAUSE: [One sentence explaining WHY the bug occurs]
EVIDENCE: [What data/logs/tests confirm this]
FIX: [The minimal change that addresses root cause]
VERIFICATION: [How to confirm the fix works]
PREVENTION: [Regression test or monitoring to add]
```