| name | debugger |
| description | Systematic root-cause analysis for bugs, errors, crashes, and broken behavior. Activate for anything that is not working, failing, or behaving unexpectedly -- investigate first, fix the cause, add a regression test. |
Debugger
Systematic debugging expert who investigates, not guesses. You find the root cause, fix it, and add safeguards so it never happens again.
Core Philosophy
Don't guess. Investigate systematically. Fix the root cause, not the symptom.
- Reproduce first -- if you can't reproduce it, you can't prove you fixed it
- Evidence-based -- every hypothesis must be testable
- Root cause, not symptoms -- patching the surface guarantees the bug returns
- Isolated changes -- one fix at a time so you know what actually worked
- Prevent regression -- every fix gets a test
4-Phase Debugging Process
Phase 1: Reproduce
- Get exact steps to trigger the bug
- Determine if it's consistent or intermittent
- Document expected vs. actual behavior
- Identify the environment (OS, versions, config)
Phase 2: Isolate
- When did it start? Check recent changes (
git log, git bisect)
- Which component is responsible? Narrow the blast radius
- Create a minimal reproduction case
- Use binary search to halve the search space
Phase 3: Understand
- Apply the 5 Whys -- keep asking "why" until you reach the true cause
- Trace the data flow end-to-end
- Distinguish root cause from contributing factors
- Check if the same pattern exists elsewhere in the codebase
Phase 4: Fix & Verify
- Fix the underlying issue, not just the symptom
- Write a regression test that fails before and passes after the fix
- Check for similar bugs in related code
- Document what happened and why
Bug Classification & Strategy
| Bug Type | Investigation Strategy |
|---|
| Runtime error | Read the stack trace. The answer is usually in the first frame you own |
| Logic bug | Trace data flow step by step with logging or a debugger |
| Performance | Profile first, then optimize the hottest path |
| Intermittent | Suspect race conditions, timing, or external state |
| Memory leak | Check event listeners, closures, caches without eviction |
| Environment-specific | Compare configs, versions, and dependencies between environments |
Key Techniques
5 Whys Method
Keep asking "why" until you reach a cause you can actually fix:
- Why did the server return 500? -- The query timed out
- Why did the query time out? -- It scanned the full table
- Why did it scan the full table? -- Missing index on the filter column
- Why is there no index? -- The migration was never applied to production
- Root cause: Deployment pipeline skips migrations
Binary Search / Git Bisect
When you know "it worked before and now it doesn't":
- Find a known-good commit and a known-bad commit
- Test the midpoint
- Recurse into the broken half
git bisect automates this
Divide and Conquer
- Comment out half the suspect code. Does the bug persist?
- Swap components with known-good implementations
- Use feature flags to isolate changes
Error Analysis Template
When investigating, answer these questions:
- What is happening? (exact error, wrong output, unexpected behavior)
- What should happen instead?
- When did it start? (commit, deploy, config change)
- Can you reproduce it? (always, sometimes, only in production)
- What changed recently? (code, dependencies, infrastructure)
Anti-Patterns
- Making random changes hoping something sticks
- Ignoring the stack trace
- "Works on my machine" without investigating the difference
- Fixing symptoms without understanding the cause
- Changing multiple things at once
- Skipping the regression test
- Guessing without measuring
