Debugging Systematically

Quick Start

Reproduce - Create reliable reproduction steps, document environment
Isolate - Binary search to narrow down, create minimal repro case
Hypothesize - Generate 3+ theories with evidence and test cost
Test - Design tests to prove/disprove each hypothesis
Fix & Verify - Write failing test first, implement fix, verify green

Features

Feature	Description	Guide
Reproduction	Consistent steps to trigger bug	Exact steps, environment, frequency
Isolation	Narrow down problem area	Binary search code, git bisect
Hypothesis Ranking	Prioritize theories to test	Evidence strength x (1/test cost)
Strategic Logging	Add targeted debug output	`[DEBUG][Service][method]` format
Git Bisect	Find regression commit	`git bisect start`, mark good/bad
Regression Tests	Prevent bug from returning	Write failing test before fixing

Common Patterns

# Reproduction Template
Environment:
  OS: [version]
  Node: [version]
  Browser: [version]

Steps:
1. [Step 1]
2. [Step 2]
3. Observe: [Error]

Frequency: 100% | Intermittent (~50%)
First observed: [date]
Last known good: [commit/version]

# Isolation via Binary Search
function problematic() {
  // BLOCK A
  await stepA1();
  await stepA2();

  // BLOCK B
  await stepB1();
  await stepB2();

  // Comment out BLOCK B
  // Still fails? Bug in BLOCK A
  // Works now? Bug in BLOCK B
}

# Git Bisect
git bisect start
git bisect bad HEAD
git bisect good v2.0.0
# Git checks out middle, test and mark
git bisect good  # or: git bisect bad
# Repeat until culprit found
git bisect reset

# Hypothesis Template
| # | Hypothesis | Evidence | Test Cost | Priority |
|---|------------|----------|-----------|----------|
| H1 | Missing index | Seq scan in EXPLAIN | Low | 1st |
| H2 | N+1 query | Loop in code | Low | 2nd |
| H3 | Memory leak | Gradual increase | High | 3rd |

Best Practices

Do	Avoid
Always reproduce before debugging	Debugging without reproduction
Write down hypotheses before testing	Testing multiple hypotheses at once
Use binary search for large codebases	Random code changes
Write failing test before fixing	Assuming cause without evidence
Document the debugging session	Ignoring intermittent bugs
Add logging strategically	Keeping debug code in production
Check for related issues	Fixing symptoms instead of root cause

Related Skills

solving-problems - 5-phase problem-solving framework
tracing-root-causes - 5 Whys and Fishbone analysis
avoiding-testing-anti-patterns - Prevent flaky tests
verifying-before-completion - Ensure fix is complete

debugging-systematically

Debugging Systematically

Quick Start

Features

Common Patterns

Best Practices

Related Skills