name: debugging description: 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. metadata: version: "1.0" allowed-tools: Bash Read

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

1. Reproduce - Get a reliable reproduction case first
2. Isolate - Binary search: remove half the variables, see if it still fails
3. Trace - Follow data flow from input to failure point
4. 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.