Debugging
Decision Tree
Bug reported → Can you reproduce it?
├─ Yes → Is it consistent?
│ ├─ Yes → Add breakpoint/logging at suspected location → Trace
│ └─ No (intermittent) → Race condition or timing issue → Add timestamps to logs
└─ No → Check environment differences
├─ Works locally, fails in CI → Compare env vars, paths, timezone
├─ Works for others, fails for me → Check local config, versions, OS
└─ Cannot reproduce anywhere → Get reproduction steps from reporter
Common Root Causes
| Symptom |
Likely Cause |
Check |
| Works locally, fails in CI |
Env vars, file paths, timezone |
Compare environments |
| Intermittent failure |
Race condition, flaky test, timeout |
Add logging, increase timeout |
| Null/undefined error |
Missing null check, async ordering |
Trace data flow backwards |
| Memory growing |
Unclosed resources, event listener leaks |
Heap snapshot before/after |
| Slow response |
N+1 queries, missing index, large payload |
Profile, check query count |
| CORS error |
Missing headers, wrong origin, preflight |
Check server response headers |
| 403/401 |
Token expired, wrong scope, missing header |
Inspect request headers |
| "It worked yesterday" |
Dependency update, config change, data change |
Check git log, dep diff, recent deploys |
| Passes alone, fails in suite |
Shared state between tests, order dependency |
Run in isolation, check setup/teardown |
Strategy
- Reproduce - Get a reliable reproduction case first
- Isolate - Binary search: remove half the variables, see if it still fails
- Trace - Follow data flow from input to failure point
- Verify - Fix should explain the symptom, not just suppress it
Anti-Patterns
- Shotgun debugging - Changing random things hoping it works. Understand first, fix second.
- Fix the symptom - Adding a null check without understanding why it's null. Find the root cause.
- "It works now" - Can't explain why it broke or why the fix works. Keep investigating.
- Printf and pray - Adding one log, running, adding another. Plan your instrumentation.
1---2name: debugging3description: Systematic diagnostic strategy with decision tree for reproducing, isolating, and tracing bugs. Use when investigating bugs, crashes, or unexpected behavior. Complements systematic-debugging workflow with concrete diagnostic patterns.4---56# Debugging78## Decision Tree910```11Bug reported → Can you reproduce it?12 ├─ Yes → Is it consistent?13 │ ├─ Yes → Add breakpoint/logging at suspected location → Trace14 │ └─ No (intermittent) → Race condition or timing issue → Add timestamps to logs15 └─ No → Check environment differences16 ├─ Works locally, fails in CI → Compare env vars, paths, timezone17 ├─ Works for others, fails for me → Check local config, versions, OS18 └─ Cannot reproduce anywhere → Get reproduction steps from reporter19```2021## Common Root Causes2223| Symptom | Likely Cause | Check |24|---------|-------------|-------|25| Works locally, fails in CI | Env vars, file paths, timezone | Compare environments |26| Intermittent failure | Race condition, flaky test, timeout | Add logging, increase timeout |27| Null/undefined error | Missing null check, async ordering | Trace data flow backwards |28| Memory growing | Unclosed resources, event listener leaks | Heap snapshot before/after |29| Slow response | N+1 queries, missing index, large payload | Profile, check query count |30| CORS error | Missing headers, wrong origin, preflight | Check server response headers |31| 403/401 | Token expired, wrong scope, missing header | Inspect request headers |32| "It worked yesterday" | Dependency update, config change, data change | Check git log, dep diff, recent deploys |33| Passes alone, fails in suite | Shared state between tests, order dependency | Run in isolation, check setup/teardown |3435## Strategy36371. **Reproduce** - Get a reliable reproduction case first382. **Isolate** - Binary search: remove half the variables, see if it still fails393. **Trace** - Follow data flow from input to failure point404. **Verify** - Fix should explain the symptom, not just suppress it4142## Anti-Patterns4344- **Shotgun debugging** - Changing random things hoping it works. Understand first, fix second.45- **Fix the symptom** - Adding a null check without understanding why it's null. Find the root cause.46- **"It works now"** - Can't explain why it broke or why the fix works. Keep investigating.47- **Printf and pray** - Adding one log, running, adding another. Plan your instrumentation.
BigPapiCB