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

Quick Reference

1. Problem Definition (CRITICAL)

• prob-reproduce-before-debug – Reproduce the bug before investigating
• prob-minimal-reproduction – Create minimal reproduction cases
• prob-document-symptoms – Document symptoms precisely
• prob-separate-symptoms-causes – Separate symptoms from causes
• prob-state-expected-actual – State expected vs actual behavior
• prob-recent-changes – Check recent changes first

2. Hypothesis-Driven Search (CRITICAL)

• hypo-scientific-method – Apply the scientific method
• hypo-binary-search – Use binary search to localize bugs
• hypo-one-change-at-time – Test one hypothesis at a time
• hypo-where-not-what – Find WHERE before asking WHAT
• hypo-rule-out-obvious – Rule out obvious causes first
• hypo-rubber-duck – Explain the problem aloud

3. Observation Techniques (HIGH)

• obs-strategic-logging – Use strategic logging
• obs-log-inputs-outputs – Log function inputs and outputs
• obs-breakpoint-strategy – Use breakpoints strategically
• obs-stack-trace-reading – Read stack traces bottom to top
• obs-watch-expressions – Use watch expressions for state
• obs-trace-data-flow – Trace data flow through system

4. Root Cause Analysis (HIGH)

• rca-five-whys – Use the 5 Whys technique
• rca-fault-propagation – Trace fault propagation chains
• rca-last-known-good – Find the last known good state
• rca-question-assumptions – Question your assumptions
• rca-examine-boundaries – Examine system boundaries

5. Tool Mastery (MEDIUM-HIGH)

• tool-conditional-breakpoints – Use conditional breakpoints
• tool-logpoints – Use logpoints instead of modifying code
• tool-step-commands – Master step over/into/out
• tool-call-stack-navigation – Navigate the call stack
• tool-memory-inspection – Inspect memory and object state
• tool-exception-breakpoints – Use exception breakpoints

6. Bug Triage and Classification (MEDIUM)

• triage-severity-vs-priority – Separate severity from priority
• triage-user-impact-assessment – Assess user impact before prioritizing
• triage-reproducibility-matters – Factor reproducibility into triage
• triage-quick-wins-first – Identify and ship quick wins first
• triage-duplicate-detection – Detect and link duplicate bug reports

7. Common Bug Patterns (MEDIUM)

• pattern-null-pointer – Recognize null pointer patterns
• pattern-off-by-one – Spot off-by-one errors
• pattern-race-condition – Identify race condition symptoms
• pattern-memory-leak – Detect memory leak patterns
• pattern-type-coercion – Watch for type coercion bugs
• pattern-async-await-errors – Catch async/await error handling mistakes
• pattern-timezone-issues – Recognize timezone and date bugs

8. Fix Verification (MEDIUM)

• verify-reproduce-fix – Verify with original reproduction
• verify-regression-check – Check for regressions
• verify-understand-why-fix-works – Understand why fix works
• verify-add-test – Add test to prevent recurrence

9. Anti-Patterns (MEDIUM)

• anti-shotgun-debugging – Avoid shotgun debugging
• anti-quick-patch – Avoid quick patches without understanding
• anti-tunnel-vision – Avoid tunnel vision on initial hypothesis
• anti-debug-fatigue – Recognize debugging fatigue
• anti-blame-tool – Don’t blame the tool too quickly

10. Prevention & Learning (LOW-MEDIUM)

• prev-document-solution – Document bug solutions
• prev-postmortem – Conduct blameless postmortems
• prev-defensive-coding – Add defensive code at boundaries
• prev-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