dev-debug

name	dev-debug
description	Debug and resolve problems. Use when the user has a bug, an error, an unexpected behavior, or wants to understand why something is not working.
allowed-tools	["Read","Glob","Grep","Bash"]
context	fork
model	opus
argument-hint	[error-description]

Debug a Problem

Goal

Identify the root cause of a bug methodically via a systematic 4-phase approach.

Systematic Methodology (4 Phases)

┌──────────────────────────────────────────────────────────────────┐
│                   SYSTEMATIC DEBUGGING                            │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  PHASE 1: OBSERVATION          Collect without interpreting       │
│  ═══════════════════                                              │
│  - Reproduce the exact symptom                                    │
│  - Document the environment                                       │
│  - Capture logs, stack traces, states                             │
│  - DO NOT jump to conclusions                                     │
│                                                                   │
│  PHASE 2: HYPOTHESES           Reason systematically              │
│  ════════════════════                                             │
│  - List ALL possible causes                                       │
│  - Rank by probability (high/medium/low)                          │
│  - Define a validation test for each hypothesis                   │
│  - Use the 5 Whys technique                                       │
│                                                                   │
│  PHASE 3: INVESTIGATION        Prove, do not assume               │
│  ══════════════════════                                           │
│  - Test ONE hypothesis at a time                                  │
│  - Use strategic tracing and logging                              │
│  - Isolate with binary search (code or git bisect)                │
│  - Document each tested hypothesis (confirmed/refuted)            │
│                                                                   │
│  PHASE 4: VERIFICATION         Confirm the fix is real            │
│  ════════════════════                                             │
│  - Reproduce the original bug (must fail without the fix)         │
│  - Apply the minimal fix                                          │
│  - Prove the bug is fixed                                         │
│  - Verify the absence of side effects                             │
│  - Add a non-regression test                                      │
│  - Defense in depth: assertions on invariants                     │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Phase 1: Observation

Key questions:

• What is happening exactly?
• What should happen?
• When did it start?
• Is it 100% reproducible?
• What are the aggravating/mitigating factors?

# Recent logs
tail -100 logs/app.log 2>/dev/null

# Latest commits
git log --oneline -10

# Recent changes in the suspect area
git log --oneline -5 -- src/path/suspect/

Phase 2: Hypotheses

Hypothesis matrix

#	Hypothesis	Probability	Validation test
1	[Most likely]	High	[How to verify]
2	[Secondary]	Medium	[How to verify]
3	[Less likely]	Low	[How to verify]

5 Whys technique

Problem: The application crashes at login

1. Why? -> The JWT token is invalid
2. Why? -> The token has expired
3. Why? -> The refresh token was not called
4. Why? -> The interceptor did not detect the expiration
5. Why? -> Timezone bug in the comparison

Root cause: Timezone bug in the refresh logic

Common causes by type

Bug type	Frequent causes
Null/Undefined	Missing data, race condition, API changed
Type error	Wrong type, JSON parsing, implicit conversion
Off-by-one	Array index, loop, < vs <= comparison
Race condition	Async without await, shared state, timing
Memory leak	Event listeners, closures, circular references
Regression	Recent change, side effect, dependency update

Phase 3: Investigation

Tracing techniques

// Strategic tracing (not console.log everywhere)
function trace(label: string, data: unknown) {
  console.log(`[TRACE:${label}]`, JSON.stringify(data, null, 2));
}

// Trace points at boundaries
trace('INPUT', { args });       // Function entry
trace('STATE', { variables });  // Intermediate state
trace('OUTPUT', { result });    // Function exit
trace('BRANCH', { condition }); // Decision taken

Binary search in the code

1. Comment out half of the suspect code
2. Does the bug persist?
   - Yes -> The bug is in the remaining half
   - No  -> The bug is in the commented half
3. Repeat until isolating the exact line

Git bisect (find the faulty commit)

git bisect start
git bisect bad                 # Current version broken
git bisect good <commit>       # Last known good version
# Test and mark good/bad until finding the commit
git bisect reset

Phase 4: Verification (MANDATORY)

Prove the fix works

1. WITHOUT the fix: reproduce the bug -> failure confirmed
2. WITH the fix: same scenario        -> success confirmed
3. Existing tests                     -> all pass
4. Non-regression test                -> written and passes
5. Side effects                       -> verified absent

Defense in depth

// Add assertions on critical invariants
function processPayment(amount: number, userId: string) {
  assert(amount > 0, 'Payment amount must be positive');
  assert(userId, 'User ID is required');
  // ...business code...
}

Completion checklist

[ ] Bug reproduced reliably
[ ] Root cause identified (not just the symptom)
[ ] Minimal fix applied (no opportunistic refactoring)
[ ] Non-regression test added
[ ] Existing tests pass
[ ] No side effects
[ ] Fix documentation (descriptive commit message)

Expected output

## Diagnosis: [Bug description]

### Phase 1 - Observation
**Symptom:** [What happens]
**Expected behavior:** [What should happen]
**Reproduction:** [Steps 1, 2, 3...]

### Phase 2 - Hypotheses
| # | Hypothesis | Probability | Result |
|---|------------|-------------|--------|
| 1 | [...] | High | Confirmed/Refuted |

### Phase 3 - Investigation
**Root cause:** `src/xxx.ts:42` - [Technical explanation]
**5 Whys:** [Causal chain]

### Phase 4 - Verification
- [x] Bug reproduced
- [x] Fix applied
- [x] Non-regression test added
- [x] All tests pass
- [x] No side effects

Rules

• Do not assume - verify (Phase 4 mandatory)
• One bug at a time
• Understand BEFORE fixing
• Always add a non-regression test
• Document every tested hypothesis, even refuted ones
• The fix must be MINIMAL - no opportunistic refactoring

Iron Law: No fix without root cause

IMPORTANT: NEVER propose a fix before identifying the root cause. Symptom fixes mask the real problem and create new bugs.

Red flags (rationalizations to avoid)

Phrase	Problem
"Quick fix for now"	Avoids the root cause
"Let's just try changing X"	Guess-and-check, not systematic
"I don't really understand but it should work"	Blind fix
"It's urgent, no time to investigate"	Systematic investigation is FASTER

Rule of 3 failures

After 3 failed fix attempts: STOP. Do not attempt a 4th fix.

1. Question the basic assumptions
2. Broaden the search perimeter
3. Check whether the problem is architectural (not just a local bug)
4. Consider git bisect to find the faulty commit

Metrics

Approach	Average time	1st-attempt fix rate
Systematic (4 phases)	15-30 min	~95%
Random fixing (guess-and-check)	2-3h	~40%