---

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

Common Patterns

Copy# 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

Copy# 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

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