dot-skills Debugging Best Practices
Comprehensive debugging methodology guide for software engineers, containing 54 rules across 10 categories prioritized by impact. Based on research from Andreas Zeller's "Why Programs Fail" and academic debugging curricula.
When to Apply
Reference these guidelines when:
- Investigating a bug or unexpected behavior
- Debugging code during development
- Code produces wrong results or crashes
- Performance issues need root cause analysis
- Triaging incoming bug reports and prioritizing fixes
- Conducting root cause analysis for incidents
- Reviewing debugging approaches or code for common bug patterns
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Problem Definition | CRITICAL | prob- |
| 2 | Hypothesis-Driven Search | CRITICAL | hypo- |
| 3 | Observation Techniques | HIGH | obs- |
| 4 | Root Cause Analysis | HIGH | rca- |
| 5 | Tool Mastery | MEDIUM-HIGH | tool- |
| 6 | Bug Triage and Classification | MEDIUM | triage- |
| 7 | Common Bug Patterns | MEDIUM | pattern- |
| 8 | Fix Verification | MEDIUM | verify- |
| 9 | Anti-Patterns | MEDIUM | anti- |
| 10 | Prevention & Learning | LOW-MEDIUM | prev- |
Quick Reference
1. Problem Definition (CRITICAL)
prob-reproduce-before-debug- Reproduce the bug before investigatingprob-minimal-reproduction- Create minimal reproduction casesprob-document-symptoms- Document symptoms preciselyprob-separate-symptoms-causes- Separate symptoms from causesprob-state-expected-actual- State expected vs actual behaviorprob-recent-changes- Check recent changes first
2. Hypothesis-Driven Search (CRITICAL)
hypo-scientific-method- Apply the scientific methodhypo-binary-search- Use binary search to localize bugshypo-one-change-at-time- Test one hypothesis at a timehypo-where-not-what- Find WHERE before asking WHAThypo-rule-out-obvious- Rule out obvious causes firsthypo-rubber-duck- Explain the problem aloud
3. Observation Techniques (HIGH)
obs-strategic-logging- Use strategic loggingobs-log-inputs-outputs- Log function inputs and outputsobs-breakpoint-strategy- Use breakpoints strategicallyobs-stack-trace-reading- Read stack traces bottom to topobs-watch-expressions- Use watch expressions for stateobs-trace-data-flow- Trace data flow through system
4. Root Cause Analysis (HIGH)
rca-five-whys- Use the 5 Whys techniquerca-fault-propagation- Trace fault propagation chainsrca-last-known-good- Find the last known good staterca-question-assumptions- Question your assumptionsrca-examine-boundaries- Examine system boundaries
5. Tool Mastery (MEDIUM-HIGH)
tool-conditional-breakpoints- Use conditional breakpointstool-logpoints- Use logpoints instead of modifying codetool-step-commands- Master step over/into/outtool-call-stack-navigation- Navigate the call stacktool-memory-inspection- Inspect memory and object statetool-exception-breakpoints- Use exception breakpoints
6. Bug Triage and Classification (MEDIUM)
triage-severity-vs-priority- Separate severity from prioritytriage-user-impact-assessment- Assess user impact before prioritizingtriage-reproducibility-matters- Factor reproducibility into triagetriage-quick-wins-first- Identify and ship quick wins firsttriage-duplicate-detection- Detect and link duplicate bug reports
7. Common Bug Patterns (MEDIUM)
pattern-null-pointer- Recognize null pointer patternspattern-off-by-one- Spot off-by-one errorspattern-race-condition- Identify race condition symptomspattern-memory-leak- Detect memory leak patternspattern-type-coercion- Watch for type coercion bugspattern-async-await-errors- Catch async/await error handling mistakespattern-timezone-issues- Recognize timezone and date bugs
8. Fix Verification (MEDIUM)
verify-reproduce-fix- Verify with original reproductionverify-regression-check- Check for regressionsverify-understand-why-fix-works- Understand why fix worksverify-add-test- Add test to prevent recurrence
9. Anti-Patterns (MEDIUM)
anti-shotgun-debugging- Avoid shotgun debugginganti-quick-patch- Avoid quick patches without understandinganti-tunnel-vision- Avoid tunnel vision on initial hypothesisanti-debug-fatigue- Recognize debugging fatigueanti-blame-tool- Don't blame the tool too quickly
10. Prevention & Learning (LOW-MEDIUM)
prev-document-solution- Document bug solutionsprev-postmortem- Conduct blameless postmortemsprev-defensive-coding- Add defensive code at boundariesprev-improve-error-messages- Improve error messages
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- Example rules: prob-reproduce-before-debug, hypo-binary-search
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md