Debugging

Version 1.0.0
dot-skills
January 2025

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive debugging methodology guide for software engineers, designed for AI agents and LLMs. Contains 54 rules across 10 categories, prioritized by impact from critical (problem definition, hypothesis-driven search) to incremental (prevention and learning). Includes bug triage, common bug patterns, and root cause analysis. Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct approaches, and specific impact metrics to guide systematic bug investigation.

Table of Contents

1. Problem Definition — CRITICAL
   • 1.1 Check Recent Changes First — CRITICAL (80%+ of bugs are caused by recent changes; reduces search space dramatically)
   • 1.2 Create Minimal Reproduction Cases — CRITICAL (Reduces debugging scope by 80-95%, making root cause obvious in many cases)
   • 1.3 Document Symptoms Precisely — CRITICAL (Prevents misdiagnosis and enables pattern matching across similar issues)
   • 1.4 Reproduce Before Debugging — CRITICAL (Prevents 50%+ of wasted debugging time on unreproducible or misunderstood issues)
   • 1.5 Separate Symptoms from Causes — CRITICAL (Prevents fixing symptoms while root cause continues creating new bugs)
   • 1.6 State Expected vs Actual Behavior — CRITICAL (Provides clear success criteria and prevents fixing the wrong thing)
2. Hypothesis-Driven Search — CRITICAL
   • 2.1 Apply the Scientific Method — CRITICAL (Eliminates 80%+ of random debugging; provides systematic path to root cause)
   • 2.2 Explain the Problem Aloud (Rubber Duck) — CRITICAL (Reveals gaps in understanding; 50%+ of bugs found during explanation)
   • 2.3 Find WHERE Before Asking WHAT — CRITICAL (Location narrows problem space by 90%+; understanding comes faster with context)
   • 2.4 Rule Out Obvious Causes First — CRITICAL (60%+ of bugs have simple causes; checking obvious things first saves hours)
   • 2.5 Test One Hypothesis at a Time — CRITICAL (Prevents confounding variables; ensures you know which change fixed the bug)
   • 2.6 Use Binary Search to Localize Bugs — CRITICAL (Reduces search space by 50% per iteration; finds bug in O(log n) steps)
3. Observation Techniques — HIGH
   • 3.1 Log Function Inputs and Outputs — HIGH (Reveals data transformation issues; enables replay debugging)
   • 3.2 Read Stack Traces Bottom to Top — HIGH (5-10× faster error localization; reveals full call chain context)
   • 3.3 Trace Data Flow Through the System — HIGH (2-5× faster bug localization; pinpoints exact transformation that corrupts data)
   • 3.4 Use Breakpoints Strategically — HIGH (10× faster inspection than print statements; enables state exploration)
   • 3.5 Use Strategic Logging Over Random Print Statements — HIGH (5× faster bug localization; structured logs enable automated analysis)
   • 3.6 Use Watch Expressions for Complex State — HIGH (3-5× faster state tracking; auto-updates computed values on each step)
4. Root Cause Analysis — HIGH
   • 4.1 Examine System Boundaries — HIGH (70%+ of bugs occur at boundaries; interfaces are high-risk areas)
   • 4.2 Find the Last Known Good State — HIGH (O(log n) regression detection via git bisect; establishes working baseline)
   • 4.3 Question Your Assumptions — HIGH (Uncovers hidden bugs; 40%+ of debugging time is wasted on false assumptions)
   • 4.4 Trace Fault Propagation Chains — HIGH (2-3× faster root cause discovery; traces infection chain from symptom to origin)
   • 4.5 Use the 5 Whys Technique — HIGH (Reaches true root cause instead of surface symptoms; prevents recurrence)
5. Tool Mastery — MEDIUM-HIGH
   • 5.1 Inspect Memory and Object State — MEDIUM-HIGH (Catches 90%+ of reference vs value bugs; reveals prototype chain and hidden properties)
   • 5.2 Master Step Over, Step Into, Step Out — MEDIUM-HIGH (Efficient navigation through code; 5× faster than random stepping)
   • 5.3 Navigate the Call Stack — MEDIUM-HIGH (3× faster context discovery; reveals parameter values at each call level)
   • 5.4 Use Conditional Breakpoints — MEDIUM-HIGH (100× faster than hitting breakpoint manually in loops; targets exact conditions)
   • 5.5 Use Exception Breakpoints — MEDIUM-HIGH (5× faster exception debugging; catches errors at throw point with full context)
   • 5.6 Use Logpoints Instead of Modifying Code — MEDIUM-HIGH (100% clean commits; zero risk of shipping debug statements to production)
6. Bug Triage and Classification — MEDIUM
   • 6.1 Assess User Impact Before Prioritizing — MEDIUM (10× improvement in value delivered per engineering hour)
   • 6.2 Detect and Link Duplicate Bug Reports — MEDIUM (prevents duplicate investigation effort)
   • 6.3 Factor Reproducibility into Triage — MEDIUM (prevents wasted investigation time)
   • 6.4 Identify and Ship Quick Wins First — MEDIUM (3-5× more bugs fixed per sprint)
   • 6.5 Separate Severity from Priority — MEDIUM (enables correct resource allocation)
7. Common Bug Patterns — MEDIUM
   • 7.1 Catch Async/Await Error Handling Mistakes — MEDIUM (prevents unhandled promise rejections)
   • 7.2 Detect Memory Leak Patterns — MEDIUM (prevents out-of-memory crashes)
   • 7.3 Identify Race Condition Symptoms — MEDIUM (prevents intermittent production failures)
   • 7.4 Recognize Null Pointer Patterns — MEDIUM (prevents 20-30% of runtime errors)
   • 7.5 Recognize Timezone and Date Bugs — MEDIUM (prevents date calculation errors across timezones)
   • 7.6 Spot Off-by-One Errors — MEDIUM (prevents 10-15% of logic errors)
   • 7.7 Watch for Type Coercion Bugs — MEDIUM (prevents silent data corruption bugs)
8. Fix Verification — MEDIUM
   • 8.1 Add a Test to Prevent Recurrence — MEDIUM (100% regression prevention for this specific bug; serves as executable documentation)
   • 8.2 Check for Regressions After Fixing — MEDIUM (Prevents fix from breaking existing functionality; catches unintended side effects)
   • 8.3 Understand Why the Fix Works — MEDIUM (Prevents cargo cult fixes; ensures fix is correct, not accidental)
   • 8.4 Verify Fix With Original Reproduction — MEDIUM (Confirms fix actually works; prevents false confidence from unrelated changes)
9. Anti-Patterns — MEDIUM
   • 9.1 Avoid Blaming the Tool Too Quickly — MEDIUM (95%+ of bugs are in your code, not libraries; premature blame wastes time)
   • 9.2 Avoid Quick Patches Without Understanding — MEDIUM (Prevents technical debt and recurring bugs; quick fixes often mask real problems)
   • 9.3 Avoid Shotgun Debugging — MEDIUM (Prevents hours of wasted effort; random changes make bugs harder to find)
   • 9.4 Avoid Tunnel Vision on Initial Hypothesis — MEDIUM (Prevents wasted hours pursuing wrong theory; 30%+ of bugs aren't where we first look)
   • 9.5 Recognize and Address Debugging Fatigue — MEDIUM (Prevents stupid mistakes from tiredness; fresh perspective finds bugs faster)
10. Prevention & Learning — LOW-MEDIUM

• 10.1 Add Defensive Code at System Boundaries — LOW-MEDIUM (Catches bugs earlier with better context; prevents cascade failures)
• 10.2 Conduct Blameless Postmortems — LOW-MEDIUM (Prevents recurrence through systemic fixes; builds team debugging culture)
• 10.3 Document Bug Solutions for Future Reference — LOW-MEDIUM (Reduces future debugging time by 40-60%; creates team knowledge base)
• 10.4 Improve Error Messages When You Debug — LOW-MEDIUM (Reduces future debugging time; helps next developer (including future you))

References

1. https://www.whyprogramsfail.com/
2. https://web.mit.edu/6.031/www/sp17/classes/11-debugging/
3. https://www.cs.cornell.edu/courses/cs312/2006fa/lectures/lec26.html
4. https://code.visualstudio.com/docs/debugtest/debugging
5. https://developer.chrome.com/docs/devtools/javascript/reference/
6. https://rubberduckdebugging.com/
7. https://git-scm.com/docs/git-bisect

Source Files

This document was compiled from individual reference files. For detailed editing or extension: