debugging-systematically

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.

📖 中文导读: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. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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
  • 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