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

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

B - Bisect and Narrow

Use binary search: Comment out code halves, use

git bisect

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

By Bug Type

Full classification: reference/bug-classification.md

Core Techniques

git bisect start/good/bad

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

Full examples: reference/anti-patterns.md

Templates

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.