debug

name: debug description: 'Systematic debugging workflow based on Kernighan, Pike, Feathers, and Gregg methodologies. Activates on keywords: debug, bug, error, issue, troubleshoot, crash, fix, broken'

Systematic Debugging

"Debugging is twice as hard as writing the code in the first place." — Brian Kernighan

The Two Schools of Debugging

Key Insight: Master debuggers combine both approaches.

Universal Debugging Protocol (UDP)

1. STOP      → Define the problem clearly (expected vs actual)
2. REPRODUCE → Create minimal, reliable reproduction
3. OBSERVE   → Collect evidence (logs, state, traces)
4. HYPOTHESIZE → Form testable hypothesis (max 3)
5. TEST      → Change ONE thing, observe result
6. FIX       → Apply minimal fix
7. VERIFY    → Confirm fix, run regression tests
8. DOCUMENT  → Record cause, solution, lessons learned

Kernighan's 9 Indispensable Rules

1. Understand the system — Read before debug
2. Make it fail — Reproducibility is everything
3. Quit thinking and look — Observe, don't assume
4. Divide and conquer — Binary search the problem space
5. Change one thing at a time — Isolate variables
6. Keep an audit trail — Log everything you try
7. Check the plug — Verify the obvious first
8. Get a fresh view — Rubber duck, colleague, or sleep on it
9. If you didn't fix it, it isn't fixed — Verify ruthlessly

Gregg's Observability Principles

USE Method (for resources)

• Utilization: How busy is the resource?
• Saturation: How much work is queued?
• Errors: Are there error events?

RED Method (for services)

• Rate: Requests per second
• Errors: Failed requests
• Duration: Latency distribution

Flame Graphs

Visualize CPU/memory hotspots. Stack depth = call chain, width = time spent.

Feathers' Legacy Code Approach

When debugging unfamiliar or legacy code:

1. Seam — Find a point to insert observation/tests
2. Cover — Add characterization test (capture current behavior)
3. Change — Modify with safety net
4. Refactor — Clean up after fixing

Anti-Patterns to Avoid

Claude Interaction Protocol

When helping with debugging, follow this workflow:

Phase 1: Problem Definition

1. ASK: "What is the expected behavior vs actual behavior?"
2. ASK: "When did this start? Any recent changes?"
3. ASK: "Is it reproducible? Steps to reproduce?"
4. CREATE: debug_notes.md to track investigation

Phase 2: Reproduction

1. ATTEMPT: Reproduce the issue
2. DOCUMENT: Steps to reproduce in debug_notes.md
3. SIMPLIFY: Find minimal reproduction case
4. IDENTIFY: Consistent vs intermittent failure

Phase 3: Investigation

1. OBSERVE: Gather logs, errors, stack traces
2. HYPOTHESIZE: Form at most 3 hypotheses
3. TEST: Each hypothesis with ONE change at a time
4. RECORD: Every attempt in debug_notes.md
5. NARROW: Use divide-and-conquer to isolate

Phase 4: Resolution

1. FIX: Apply minimal fix
2. VERIFY: Confirm fix works
3. REGRESS: Check for side effects
4. PREVENT: Add test if appropriate
5. SUMMARIZE: Root cause and solution in debug_notes.md

debug_notes.md Template

Create this file to track debugging investigations:

# Debug Notes: [Issue Description]

## Problem Statement
- **Expected**: [what should happen]
- **Actual**: [what happens]
- **Severity**: [critical/high/medium/low]
- **First observed**: [when]

## Environment
- OS:
- Version:
- Dependencies:

## Reproduction Steps
1. [step]
2. [step]
3. [observe failure]

## Hypotheses
- [ ] H1: [hypothesis] — [how to test]
- [ ] H2: [hypothesis] — [how to test]
- [ ] H3: [hypothesis] — [how to test]

## Investigation Log

| Time | Action | Result | Next Step |
|------|--------|--------|-----------|
| | | | |

## Root Cause
[Explanation of why the bug occurred]

## Solution
[What was changed and why]

## Prevention
[How to prevent similar issues: tests, guards, docs]

Quick Decision Tree

Problem reported
    │
    ▼
Can reproduce? ─No──▶ Get more info (logs, environment)
    │
   Yes
    │
    ▼
Recent change? ─Yes──▶ Check diff, rollback test
    │
    No
    │
    ▼
Obvious cause? ─Yes──▶ Verify with minimal test
    │
    No
    │
    ▼
Divide and conquer
    │
    ▼
Isolate component
    │
    ▼
Form hypothesis (max 3)
    │
    ▼
Test ONE change at a time
    │
    ▼
Fix → Verify → Document

Domain-Specific Checklists

See checklists.md for:

• Streaming/Buffer Issues
• BLE/UART Communication
• AI Inference Bottlenecks
• System Observability
• Network/API Issues
• Memory/Crash Issues
• App Debugging
• Web Debugging

Tool Reference

See reference.md for tool commands and recipes.