debugging-protocol

What this skill does

# Debugging Protocol

**Version:** 1.0.0
**Portability:** Universal

---

## Objective

Defines a systematic 4-phase investigation process for debugging any bug, test failure, or unexpected behavior. Enforces root cause analysis before attempting fixes.

**Purpose:** Prevent symptom fixes (which hide bugs) and ensure deep understanding of problems before implementing solutions.

**Scope:**
- **Included:** Investigation methodology, hypothesis testing, pattern analysis, verification steps
- **Excluded:** Language-specific debugging tools (framework-agnostic principles)

---

## Core Principles

### Principle 1: No Fixes Without Investigation (The Iron Law)

**The Iron Law:** Never attempt a fix until you complete root cause investigation.

**Why this matters:** Symptom fixes hide bugs rather than solving them. They create technical debt, mask deeper issues, and often cause new bugs elsewhere.

**How to apply:**
- When you see a bug, resist the urge to "just fix it"
- Complete all 4 phases before changing code
- If you're tempted to skip investigation, that's a red flag

**Example:**
```
❌ Bad: "Error says null pointer. Let me add a null check."
✓ Good: "Error says null pointer. Why is this null? (investigate)"

Result:
- Bad approach: Symptom fixed, root cause remains, bug appears elsewhere
- Good approach: Found initialization bug, fixed at source, entire class prevented
```

### Principle 2: Four-Phase Investigation Process

**The Principle:** Follow a structured investigation: Root Cause → Pattern Analysis → Hypothesis Testing → Implementation.

**Why this matters:** Structured investigation prevents random debugging and ensures you understand the problem completely before attempting solutions.

**The Four Phases:**
1. **Root Cause Investigation:** Understand WHAT is happening
2. **Pattern Analysis:** Find working examples to compare against
3. **Hypothesis Testing:** Form and test a single theory
4. **Implementation:** Fix with confidence

**How to apply:** Complete each phase before moving to the next. Document your findings at each phase.

### Principle 3: One Hypothesis at a Time

**The Principle:** Test a single hypothesis with minimal changes. If it fails, undo and try a different theory.

**Why this matters:** Changing multiple things simultaneously makes it impossible to know which change had which effect. This wastes time and compounds confusion.

**How to apply:**
1. State your hypothesis explicitly: "I believe the bug is caused by [X]"
2. Make ONE change to test it
3. Observe the result
4. If wrong, UNDO the change
5. Form a new hypothesis with new information

**Example:**
```
❌ Bad: "Let me change the import, add a null check, and update the type signature"
✓ Good:
  - Hypothesis 1: "The import is wrong" → Test → Refuted → Undo
  - Hypothesis 2: "The type is incorrect" → Test → Confirmed → Fix

Result: Clear understanding of what actually solved the problem
```

### Principle 4: Escalation After Three Failures

**The Principle:** If three fix attempts fail, stop trying fixes. The problem is deeper than you think.

**Why this matters:** Repeated failures signal architectural problems or domain modeling issues, not simple bugs. Continuing to try fixes wastes time.

**How to apply:**
- Track your fix attempts
- After 3 failures, STOP
- Return to Phase 1 with a new question: "Why do my fixes keep failing?"
- Consider whether this is a design problem, not a bug

**Example:**
```
Attempt 1: Add validation → Still fails
Attempt 2: Change order → Still fails
Attempt 3: Different algorithm → Still fails

STOP. Question the architecture:
- Are we solving the wrong problem?
- Is the domain model incorrect?
- Is this a fundamental design issue?
```

---

## Constraints and Boundaries

### DO:
- Complete root cause investigation before attempting any fix
- Read error messages fully (not just the first line)
- Reproduce bugs consistently before debugging
- Compare against working examples
- Test one hypothesis at a time
- Create failing tests before fixes
- Stop after 3 failed attempts and reconsider

### DON'T:
- Jump straight to a fix without investigation (symptom fixing)
- Skim error messages or stack traces
- Try "a few things" to see what works (random debugging)
- Change multiple things simultaneously
- Assume "it worked before, must be environment" without evidence
- Continue after 3 failed fixes (escalate instead)
- Add checks that prevent errors without understanding why they occur

**Rationale:** Disciplined investigation finds root causes. Random debugging wastes time and hides problems.

---

## Usage Patterns

### Pattern 1: Test Failure Investigation

**Scenario:** Test that passed before now fails after code changes.

**Approach:**

**Phase 1: Root Cause Investigation**
1. Read full error message and stack trace
2. Reproduce consistently (does it fail every time?)
3. Check recent changes:
   ```bash
   git diff HEAD~5  # What changed?
   git log --oneline -10  # Recent commits
   ```
4. Note exact file:line where failure occurs

**Phase 2: Pattern Analysis**
1. Find similar tests that pass
2. Compare test setup, assertions, data
3. Identify differences (imports, state, configuration)

**Phase 3: Hypothesis Testing**
1. Hypothesis: "The bug was introduced in commit X"
2. Test: Checkout commit before X, run test
3. Result: Test passes → Hypothesis confirmed
4. Review changes in commit X to find root cause

**Phase 4: Implementation**
1. Create minimal test reproducing the bug
2. Fix the root cause identified in commit X
3. Verify: New test passes, all other tests pass

### Pattern 2: Multi-Component System Debugging

**Scenario:** Error occurs in distributed system (frontend → API → database).

**Approach:**

**Phase 1: Root Cause Investigation**
1. Add diagnostic logging at component boundaries
2. Trace data flow through the system
3. Identify WHERE the bug first manifests (which component?)
4. Trace data backward from error to origin

**Phase 2: Pattern Analysis**
1. Find working requests/transactions
2. Compare successful vs failing data flow
3. Identify differences in data shape, timing, state

**Phase 3: Hypothesis Testing**
1. Hypothesis: "The API is receiving malformed data from frontend"
2. Test: Log API inputs, compare to expected schema
3. Result: Confirmed - frontend sending string where number expected

**Phase 4: Implementation**
1. Add validation at API entry point (defense)
2. Fix frontend to send correct type (root cause)
3. Add integration test covering this data flow

### Pattern 3: Escalation to Architecture Review

**Scenario:** Three fix attempts have failed.

**Approach:**

**After 3rd failure:**
1. STOP attempting fixes
2. Document what you've tried and why each failed
3. Ask architectural questions:
   - Is this the wrong abstraction?
   - Is the domain model accurate?
   - Are we solving the wrong problem?
4. Seek broader review (team discussion, pair debugging, domain expert)

**Example:**
```
Problem: "User authentication fails intermittently"

Attempt 1: Add retry logic → Still fails
Attempt 2: Increase timeout → Still fails
Attempt 3: Better error handling → Still fails

STOP. Architectural questions:
- Is session management the right approach?
- Should this be stateless with tokens instead?
- Is the database schema correct?

Result: Discovered fundamental session model flaw, redesigned auth flow
```

---

## Integration with Other Skills

**Works well with:**
- **tdd-constraints:** When test fails, use debugging protocol to investigate before modifying code
- **user-input-protocol:** When debugging hits ambiguous decision point, pause and ask user
- **domain-modeling:** If 3+ fixes fail, escalate to domain agent for modeling review

**Prerequisites:**
- Source control (git) for checking recent changes
- Test suite for verification
- Ability to reproduce bugs consistently

---

## Common Pitfalls

### Pitfall 1: Jumping to a Fix

**Problem:** "I know what this is, let me just fix it" (skipping investigat