tomevault-io 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 frameworktracing-root-causes- 5 Whys and Fishbone analysisavoiding-testing-anti-patterns- Prevent flaky testsverifying-before-completion- Ensure fix is complete
Converted and distributed by TomeVault — claim your Tome and manage your conversions.