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.