122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
---
|
|
name: debugging
|
|
description: Systematic debugging that identifies root causes rather than treating symptoms. Uses sequential thinking for complex analysis, web search for research, and structured investigation to avoid circular reasoning and whack-a-mole fixes.
|
|
---
|
|
|
|
# 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`
|