systematic-debugging skill

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