test-driven-fix

# Test-Driven Fix Protocol

## When This Skill Activates
- "Write a test first", "fix with TDD", "test-driven fix"
- "Reproduce with a test", "make the tests pass"
- Bug fixes where a test suite already exists
- Iterative fix cycles where verification is automated
- After 2+ failed fix attempts on the same bug (escalation)

## Anti-Hallucination Rules (NEVER violate)

| Rule | Description |
|------|-------------|
| **TEST MUST FAIL FIRST** | Never skip the "reproduce" step. The test MUST fail before you fix anything, proving it captures the bug |
| **MINIMAL FIX ONLY** | Fix the bug, not the neighborhood. Don't refactor, don't add features, don't "improve" surrounding code |
| **NO BLIND RETRIES** | If a fix doesn't work, DIAGNOSE why before trying again. Never retry the same approach |
| **EVIDENCE AT EVERY STEP** | Show test output at each phase. User should see: failing test → diagnosis → fix → passing test |
| **FULL SUITE AFTER FIX** | After your fix passes the targeted test, run the FULL test suite. No regressions allowed |
| **3-ATTEMPT LIMIT** | If 3 fix attempts fail, STOP and escalate to the user with findings so far |

## The Loop: REPRODUCE → DIAGNOSE → FIX → VALIDATE

### Phase 1: REPRODUCE (Write or Identify Failing Test)

**If tests already exist:**
```bash
# Run existing tests to identify failures
npm test          # or: bun test, pytest, cargo test, etc.

# Isolate the specific failing test
npm test -- --grep "test name"
```

**If no test captures the bug, write one:**
```typescript
// The test MUST:
// 1. Set up the exact conditions that trigger the bug
// 2. Assert the EXPECTED behavior (what should happen)
// 3. FAIL with the current code (proving it catches the bug)

describe('BugDescription', () => {
  it('should [expected behavior] when [condition]', () => {
    // Arrange: set up the bug conditions
    const input = /* exact input that triggers the bug */;

    // Act: run the code
    const result = functionUnderTest(input);

    // Assert: what SHOULD happen (this will fail now)
    expect(result).toBe(expectedValue);
  });
});
```

**Run the test — it MUST fail:**
```bash
npm test -- --grep "BugDescription"
# Expected: FAIL (this proves the test captures the bug)
```

If the test passes immediately, your test doesn't capture the bug. Rewrite it.

### Phase 2: DIAGNOSE (Understand Root Cause)

Before writing any fix:
```
1. Read the failing test output carefully
2. Read the relevant source code (use Read, Grep, Glob)
3. Trace the execution path from input to failure point
4. Form a specific hypothesis:
   - NOT: "something is wrong"
   - YES: "fetchUser returns null when id=0 because the falsy check treats 0 as missing"
5. Document your hypothesis before proceeding
```

**Use TodoWrite to track your diagnosis:**
```
[ ] Identified failing test and its assertion
[ ] Read source code at failure point
[ ] Formed specific hypothesis with evidence
[ ] Planned minimal fix
```

### Phase 3: FIX (Implement Minimal Change)

Apply the smallest possible change that addresses the root cause:
```
- Change ONLY the lines needed to fix the bug
- Do NOT refactor surrounding code
- Do NOT add "nice-to-have" improvements
- Do NOT change unrelated files
- If fix requires changes in multiple files, verify each file path before editing
```

### Phase 4: VALIDATE (Run Tests)

**Step 1: Run the targeted test**
```bash
npm test -- --grep "BugDescription"
# Expected: PASS
```

**Step 2: Run the full test suite**
```bash
npm test
# Expected: ALL PASS (no regressions)
```

**Step 3: If targeted test fails → back to Phase 2**
```
- Do NOT retry the same fix
- Re-read the test output
- What's different from your hypothesis?
- Form a NEW hypothesis based on the new evidence
- Track attempt number (max 3 before escalation)
```

**Step 4: If full suite has regressions → adjust fix**
```
- Read the newly failing tests
- Your fix broke something else
- Adjust fix to handle both cases
- Re-run full suite
```

**Step 5: Only when ALL tests pass:**
```bash
# Commit with descriptive message
git add [specific files]
git commit -m "fix: [description of what was fixed and why]"
```

## Attempt Tracking

Track each fix attempt:

```markdown
### Attempt 1
- Hypothesis: [what you thought was wrong]
- Fix applied: [what you changed]
- Result: FAIL — [why it failed]
- Learning: [what you learned]

### Attempt 2
- Hypothesis: [updated hypothesis based on attempt 1]
- Fix applied: [different approach]
- Result: PASS/FAIL
```

After 3 failed attempts:
```markdown
### Escalation
- Bug: [description]
- 3 attempts tried: [summary]
- Evidence gathered: [what we know]
- Remaining hypotheses: [what hasn't been tried]
- Recommendation: [suggested next step]
```

## Framework-Specific Commands

| Framework | Run All | Run Specific | Watch Mode |
|-----------|---------|-------------|------------|
| Jest | `npm test` | `npm test -- --grep "name"` | `npm test -- --watch` |
| Vitest | `npx vitest` | `npx vitest -t "name"` | `npx vitest --watch` |
| Bun | `bun test` | `bun test --grep "name"` | N/A |
| Pytest | `pytest` | `pytest -k "name"` | `pytest-watch` |
| Cargo | `cargo test` | `cargo test test_name` | `cargo watch -x test` |
| Playwright | `npx playwright test` | `npx playwright test -g "name"` | N/A |

## Verification Checklist
- [ ] Failing test exists that reproduces the bug (test fails before fix)
- [ ] Root cause diagnosed with specific hypothesis and evidence
- [ ] Fix is minimal (only touches code needed to fix the bug)
- [ ] Targeted test now passes
- [ ] Full test suite passes (no regressions)
- [ ] Fix committed with descriptive message
- [ ] If 3 attempts failed: escalated to user with findings

## Key Principle
**The test is your contract.** Write a test that fails because of the bug, then make it pass with the smallest possible change. If you can't make it pass in 3 attempts, you don't understand the bug well enough yet — escalate with your evidence, don't keep guessing.