Debugging Mastery Skill

Overview

Key Principle: Root cause over symptom treatment. Never be satisfied with making symptoms disappear. Understand WHY the bug occurred.

When to Use

MUST USE when:

Bug spans multiple files or components
Involves race conditions or timing issues
Has eluded initial investigation (>30 minutes)
Symptoms are intermittent or hard to reproduce
Previous fix attempts have failed

SHOULD USE when:

Bug is in unfamiliar code
Error messages are unclear or misleading
Multiple hypotheses are possible

The DEBUG Framework

D → E → B → U → G
│   │   │   │   │
│   │   │   │   └─ GUARD: Fix and prevent regression
│   │   │   └───── UNCOVER: Find root cause (5 Whys)
│   │   └───────── BISECT: Narrow down location
│   └───────────── EXPLORE: Gather evidence
└───────────────── DEFINE: Expected vs Actual

| Phase | Purpose | Key Action | Output | |-------|---------|------------|--------| | D | Define | State expected vs actual | Problem statement | | E | Explore | Gather evidence, logs, recent changes | Evidence list | | B | Bisect | Narrow down with binary search | Suspect location | | U | Uncover | Apply 5 Whys to find root cause | Root cause | | G | Guard | Fix + regression test | Verified fix |

D - Define the Problem

State clearly: Expected vs Actual behavior, reproduction steps, environment.

E - Explore Evidence

Collect: Full stack traces, surrounding logs, recent changes (git log), affected scope.

B - Bisect and Narrow

Use binary search: Comment out code halves, use git bisect, create minimal reproduction.

U - Uncover Root Cause

Apply 5 Whys: Ask "why" until you reach an actionable fix point. Verify: "If we fix this, would the bug have been prevented?"

G - Guard Against Recurrence

Fix the root cause (not symptom), add regression test, check for similar patterns elsewhere.

Full framework details: reference/debugging-techniques.md

Bug Classification Quick Reference

By Reproducibility

| Type | Debugging Approach | |------|-------------------| | 100% Reproducible | Standard: breakpoints, logging | | Intermittent | Logging, state capture, timing analysis | | Rare | Defensive logging, assertions, monitoring |

By Bug Type

| Type | Symptoms | Primary Technique | |------|----------|-------------------| | Logic | Wrong output | Code review, test cases | | State | Corruption, unexpected values | State logging | | Timing | Race conditions, deadlocks | Thread analysis | | Resource | Leaks, exhaustion | Profiling | | Integration | API mismatches | Interface comparison | | Environment | "Works on my machine" | Config diff |

Full classification: reference/bug-classification.md

Core Techniques

| Technique | When to Use | Key Command | |-----------|-------------|-------------| | 5 Whys | Unclear cause | Ask "why" 5 times | | Git Bisect | Regression | git bisect start/good/bad | | Binary Search | Large codebase | Comment out halves | | Isolation | Complex bug | Create minimal repro | | Rubber Duck | Stuck | Explain code line-by-line | | Printf Debug | No debugger | Strategic print statements |

Git Bisect Quick Reference

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Test and mark: git bisect good OR git bisect bad
# Repeat until culprit found
git bisect reset

Full techniques: reference/debugging-techniques.md

Root Cause Analysis

The 5 Whys Process

Problem: API returns 500 error
  ↓ Why?
Database query failed
  ↓ Why?
Connection pool exhausted
  ↓ Why?
Connections not released
  ↓ Why?
Exception handler missing close()
  ↓ Why?
Template code lacked finally block
  ↓
ROOT CAUSE: Missing resource cleanup pattern

Stop when: You reach an actionable fix within your control.

Verify: "If we fix this, would the problem have been prevented?"

Full RCA guide: reference/root-cause-analysis.md

Subagent Integration

When to Escalate to `debugger` Subagent

Standard techniques haven't worked after 3 attempts
Bug requires multi-codebase analysis
Need advanced reasoning (Ultrathink methodology)
Complex distributed system issues

Handoff Protocol

Provide: Bug summary, DEBUG progress so far, files involved, hypotheses tested, specific request.

Iteration Tracking

The debugger subagent has a 5-iteration limit. Track attempts and escalate if needed.

Quality Checklist

Must Pass

[ ] Root cause identified (not just symptom)
[ ] Fix tested (reproduction steps no longer work)
[ ] Regression test added
[ ] No new bugs introduced

Should Pass

[ ] Similar patterns checked elsewhere
[ ] Documentation updated if process gap found
[ ] Code review complete

Anti-Patterns

| Anti-Pattern | Why It's Bad | Better Approach | |--------------|--------------|-----------------| | Shotgun debugging | Random changes | Use DEBUG framework | | Fixing symptoms | Bug will return | Find root cause | | Skipping reproduction | Can't verify fix | Always reproduce first | | Ignoring intermittent | Gets worse | Add logging, capture state | | Debug in production | High risk | Reproduce locally | | Assuming the obvious | Wastes time | Verify with tests | | Not adding tests | Bug will recur | Always add regression test |

Full examples: reference/anti-patterns.md

Templates

| Template | Purpose | |----------|---------| | templates/debugging-session.md | Track entire session | | templates/root-cause-report.md | Document RCA | | templates/hypothesis-log.md | Track hypotheses |

Quick DEBUG Template

## Quick DEBUG

**D - Define:**
Expected: [what should happen]
Actual: [what happens]
Steps: [to reproduce]

**E - Explore:**
Error: [full message]
Changed: [recent changes]
Scope: [who's affected]

**B - Bisect:**
Last working: [commit/date]
First broken: [commit/date]
Narrowed to: [component/file]

**U - Uncover:**
Why 1: [symptom reason]
Why 2: [deeper reason]
Why 3: [root cause]

**G - Guard:**
Fix: [what to change]
Test: [regression test]

Reference Documentation

reference/root-cause-analysis.md - 5 Whys, Fishbone, Fault Trees
reference/debugging-techniques.md - Binary search, git bisect, isolation
reference/bug-classification.md - Bug types and approaches
reference/anti-patterns.md - Common mistakes

Remember: A bug isn't fixed until you understand WHY it occurred and have prevented it from recurring.