debugging-systematically

name	debugging-systematically
description	AI agent follows a 5-phase debugging process with reproduction, isolation, hypothesis testing, and root cause resolution. Use when investigating bugs, troubleshooting issues, or hunting errors.

Debugging Systematically

Quick Start

1. Reproduce - Create reliable reproduction steps, document environment
2. Isolate - Binary search to narrow down, create minimal repro case
3. Hypothesize - Generate 3+ theories with evidence and test cost
4. Test - Design tests to prove/disprove each hypothesis
5. 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