debugging

# Debugging ## Quickstart 1. Capture exact repro, scope, and recent changes 2. Isolate components/files; trace path to failure 3. Research exact error; check official docs 4. Compare failing vs working patterns; form a testable hypothesis 5. Verify with minimal test; apply minimal fix across all instances; validate ## When to Use This Skill Use debugging when: - A bug has no obvious cause or has been "fixed" before but returned - Error messages are unclear or misleading - Multiple attempted fixes have failed - The issue might affect multiple locations in the codebase - Understanding the root cause is critical for proper resolution Skip this skill for: - Simple syntax errors with obvious fixes - Trivial typos or missing imports - Well-understood, isolated bugs with clear solutions ## Core Anti-Patterns to Avoid Based on documented failures in AI debugging, explicitly avoid: 1. **Circular Reasoning**: Never propose the same fix twice without learning why it failed 2. **Premature Victory**: Always verify fixes were actually implemented and work 3. **Pattern Amnesia**: Maintain awareness of established code patterns throughout the session 4. **Context Overload**: Use the 50% rule - restart conversation when context reaches 50% 5. **Symptom Chasing**: Resist fixing error messages without understanding root causes 6. **Implementation Before Understanding**: Never jump to code changes before examining existing patterns ## UNDERSTAND (10-step checklist) - Understand: capture exact repro, scope, and recent changes - Narrow: isolate components/files; trace path to failure - Discover: research exact error (WebSearch → Parallel Search, Context7:get-library-docs) - Examine: compare against known-good patterns in the codebase - Reason: use SequentialThinking:process_thought and 5 Whys to reach root cause - Synthesize: write a falsifiable hypothesis with predictions - Test: add logs/tests to confirm the mechanism - Apply: minimal fix for root cause, across all occurrences, following patterns - Note: record insights, warnings, decisions - Document: update comments/docs/tests as needed ## Progress Tracking with TodoWrite Use TodoWrite to track debugging progress through the UNDERSTAND checklist: 1. **At start**: Create todos for each applicable step: ``` ☐ U - Capture exact repro and scope ☐ N - Isolate failing component ☐ D - Research error message ☐ E - Compare with working patterns ☐ R - Root cause analysis (5 Whys) ☐ S - Write falsifiable hypothesis ☐ T - Verify with minimal test ☐ A - Apply fix across all occurrences ☐ N - Record insights ☐ D - Update docs/tests ``` 2. **During debugging**: Mark steps in_progress → completed as you work through them 3. **When stuck**: TodoWrite makes it visible which step is blocked - helps identify if you're skipping steps or going in circles 4. **Skip steps only if**: Bug is simple enough that checklist is overkill (see "Skip this skill for" above) ## Tool Decision Tree - Know exact text/symbol? → grep - Need conceptual/semantic location? → codebase_search - Need full file context? → read_file - Unfamiliar error/behavior? → Context7:get-library-docs, then WebSearch → Parallel Search - Complex multi-hypothesis analysis? → SequentialThinking:process_thought ## Context Management - Restart at ~50% context usage to avoid degraded reasoning - Before restart: summarize facts, hypothesis, ruled-outs, next step - Start a fresh chat with just that summary; continue ## Decision Framework **IF** same fix proposed twice → Stop; use SequentialThinking:process_thought **IF** error is unclear → Research via WebSearch → Parallel Search; verify with docs **IF** area is unfamiliar → Explore with codebase_search; don't guess **IF** fix seems too easy → Confirm it addresses root cause (not symptom) **IF** context is cluttered → Restart at 50% with summary **IF** multiple hypotheses exist → Evaluate explicitly (evidence for/against) **IF** similar code works → Find and diff via codebase_search/read_file **IF** declaring success → Show changed lines; test fail-before/pass-after **IF** fix spans multiple files → Search and patch all occurrences **IF** library behavior assumed → Check Context7:get-library-docs ## Quality Checks Before Finishing Before declaring a bug fixed, verify: - [ ] Root cause identified and documented - [ ] Fix addresses cause, not symptom - [ ] All occurrences fixed (searched project-wide) - [ ] Follows existing code patterns - [ ] Original symptom eliminated - [ ] No regressions introduced - [ ] Tests/logs verify under relevant conditions - [ ] Docs/tests updated (comments, docs, regression tests) ## References - `reference/root-cause-framework.md` - `reference/antipatterns.md`