debugging

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.