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

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

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)

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