Systematic Debugging

---
name: systematic-debugging
description: 4-phase debugging protocol for diagnosing and fixing failing tests
methodology: tdd
---

# Systematic Debugging Skill

Diagnose and fix failing tests using a structured 4-phase protocol.
This skill is used by the Debugger when tests are failing and the cause
is not immediately obvious.

## The 4-Phase Protocol

### Phase 1: REPRODUCE

1. Identify the failing test(s) exactly.
   - Run the test suite and capture the exact failure output
   - Note the assertion that failed and the expected vs actual values
   - Record whether the failure is consistent or flaky

2. Create a minimal reproduction.
   - Isolate the failing test from its suite
   - Remove any unrelated setup or fixtures
   - Confirm the minimal test still fails

3. Document what you know.
   - When did the test start failing? (after which commit?)
   - Does it fail on all machines or just some environments?
   - Is the failure deterministic?

### Phase 2: ISOLATE

1. Identify the failure boundary.
   - Is the bug in the test itself (wrong assertion) or in the code under test?
   - Add temporary logging or debug output at key points
   - Use a binary search approach: remove half the code, check if still failing

2. Check common causes first.
   - Off-by-one errors in loops
   - Nil pointer dereference or missing initialization
   - Incorrect error handling (error swallowed, wrong type)
   - State leaking between tests (missing cleanup)
   - Race condition (run with `-race` flag)
   - Wrong mock or stub behavior

3. Trace the data flow.
   - Follow the input through each transformation
   - Compare the actual intermediate values against expected values
   - Find the first point where actual diverges from expected

### Phase 3: FIX

1. Make the smallest targeted fix.
   - Change ONLY what is necessary to fix the identified root cause
   - Do not refactor or clean up while fixing
   - If the fix requires a larger change, note it but keep it separate

2. Verify the fix addresses the root cause.
   - Explain in a comment why the fix works
   - Ensure the fix does not introduce new edge cases

3. Run the previously-failing test. It must now pass.

### Phase 4: VERIFY

1. Run the full test suite to ensure no regressions.
2. Run with race detection: `go test -race ./...`
3. If the bug was subtle, add a regression test that would have caught it.
4. Document the root cause and fix for future reference.

## Output Format

```
## Debug Report

### Failure Summary
- Test: <test name>
- Assertion: expected <X>, got <Y>
- Consistent/Flaky: <consistent|flaky>

### Root Cause
<Explanation of what caused the failure>

### Fix Applied
<Description of the change and why it works>

### Verification
- Failing test now passes: ✓
- Full suite passing: ✓
- Race detector clean: ✓

### Regression Test Added
<Yes/No and why>
```