playbooks

home / skills / mcouthon / agents / debug

debug skill

/generated/claude/skills/debug

This skill guides hypothesis-driven debugging to identify root causes, reproduce failures, and verify minimal fixes with regression tests.

npx playbooks add skill mcouthon/agents --skill debug

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
5.0 KB
---
name: debug
description: "Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix this issue', 'investigate', 'tests failing', 'trace the error', 'use debug mode'. Full access mode - can run commands, add logging, and fix issues."
allowed-tools: [Read, Edit, Write, Bash, Grep, Glob, LSP]
---

# Debug Mode

Systematic bug investigation and resolution.

## Core Approach

> "Don't guess. Form hypotheses. Test them."

## The 4-Phase Process

### Phase 1: Assessment 🔍

**Goal**: Understand and reproduce

- What is the expected behavior?
- What is the actual behavior?
- Can you reliably reproduce?
- What changed recently?

**Key Questions**:

- When did this start happening?
- Does it happen consistently or intermittently?
- What are the exact inputs that trigger it?
- What error messages or symptoms appear?

### Phase 2: Investigation 🔬

**Goal**: Isolate and trace

- Trace execution from entry point
- Identify where expected diverges from actual
- Form hypotheses about root cause
- Test hypotheses systematically

**Techniques**:

- Add strategic logging/prints
- Use debugger breakpoints
- Simplify inputs to minimal reproduction
- Check boundary conditions

### Phase 3: Resolution 🔧

**Goal**: Fix minimally and verify

- Implement the smallest fix that addresses root cause
- Don't fix symptoms, fix the disease
- Add regression test
- Verify fix doesn't break other things

**If fix doesn't work:**

- Count: How many fixes attempted?
- If < 3: Return to Phase 1, re-analyze with new information
- If ≥ 3: STOP. Question your understanding of the system.

### Phase 4: Quality ✅

**Goal**: Prevent recurrence

- Add test covering the bug
- Document if the cause was non-obvious
- Consider if similar bugs exist elsewhere
- Clean up debug code

## Debugging Checklist

```markdown
- [ ] **Reproduced**: Can trigger bug consistently
- [ ] **Isolated**: Know which component is failing
- [ ] **Root Cause**: Understand WHY it fails
- [ ] **Fixed**: Minimal change addresses cause
- [ ] **Tested**: Regression test added
- [ ] **Clean**: Debug code removed
```

## Hypothesis Template

```markdown
**Hypothesis**: [What you think is wrong]
**Test**: [How you'll verify]
**Result**: [What happened]
**Conclusion**: [Confirmed/Rejected/Needs more info]
```

## Common Root Causes

| Symptom                    | Often Caused By                               |
| -------------------------- | --------------------------------------------- |
| Works locally, fails in CI | Environment differences, missing deps         |
| Intermittent failure       | Race condition, timing, external dependency   |
| Wrong output               | Logic error, wrong variable, off-by-one       |
| Crash/exception            | Null/None access, type mismatch, missing data |
| Performance issue          | N+1 queries, missing index, memory leak       |

## Rationalization Prevention

| Excuse                                         | Reality                                              |
| ---------------------------------------------- | ---------------------------------------------------- |
| "I'll just add a quick fix"                    | Quick fixes hide root cause. Follow Phase 1 first.   |
| "It's probably X"                              | "Probably" isn't evidence. Test the hypothesis.      |
| "This is too simple to debug formally"         | Simple bugs waste the most time when undiagnosed.    |
| "I've tried 3 things, might as well try a 4th" | STOP. Return to Phase 1. Re-analyze with new info.   |
| "It works now, not sure why"                   | If you don't know why it works, it will break again. |

## Red Flags - STOP and Re-Assess

- Adding a 3rd fix attempt without returning to Phase 1
- Saying "should work now" without verification
- Fixing a symptom because root cause is unclear
- Skipping reproduction because "I know what's wrong"
- Multiple hypotheses being tested simultaneously

## Debug Report Format

```markdown
## Debug Report

### Bug Summary

- **Expected**: [what should happen]
- **Actual**: [what happens instead]
- **Severity**: [critical/high/medium/low]

### Reproduction

1. [Step to reproduce]
2. [Step to reproduce]
3. [Observe bug]

**Minimal reproduction**: [simplest case that triggers bug]

### Investigation

| Hypothesis | Test           | Result                     |
| ---------- | -------------- | -------------------------- |
| [theory]   | [what I tried] | ✅ Confirmed / ❌ Rejected |

### Root Cause

[What's actually wrong and why]

### Fix Applied

- **File**: `path/to/file.py`
- **Change**: [what was modified]
- **Why**: [how this fixes the root cause]

### Verification

- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] Regression test added: `test_name`
- [ ] No debug code left behind

### Prevention

[How to prevent similar bugs in the future]
```

Overview

This skill provides a structured, hypothesis-driven debugging workflow for reproducible bug investigation and efficient resolution. It guides you through assessment, targeted investigation, minimal fixes, and quality steps to prevent regressions. Use it when tests fail, unexpected errors occur, or behavior differs from expectations.

How this skill works

The skill inspects failures by reproducing the issue, tracing execution, and forming testable hypotheses about root causes. It supports adding logging, running commands, and iterating through small, verifiable fixes. After a fix, it verifies with regression tests and cleans up debug artifacts to keep the codebase healthy.

When to use it

  • When tests are failing or flaky in CI or locally
  • When an error or crash appears with unclear origin
  • When behavior diverges from specification or expected output
  • When intermittent or environment-specific failures occur
  • When you need a repeatable, documented debugging process

Best practices

  • Reproduce the bug consistently before changing code
  • Form explicit hypotheses and design tests to confirm or reject each
  • Make the smallest change that addresses the root cause
  • Add a regression test that covers the failure path
  • Remove debug logging and prints once verified
  • If multiple fixes fail, return to assessment and re-evaluate assumptions

Example use cases

  • Investigate a failing CI job that passes locally by comparing environment and dependencies
  • Trace a crash to a null/None access and apply a minimal defensive fix with a unit test
  • Isolate an intermittent race condition using simplified inputs and targeted logging
  • Resolve wrong output by tracing variable values and applying a logic correction plus regression test
  • Add a failing test to reproduce a production bug, implement fix, then verify and clean debug artifacts

FAQ

How many fixes should I attempt before re-assessing?

Stop after three unsuccessful fixes. Return to the assessment phase to re-evaluate reproduction, inputs, and hypotheses.

What belongs in the debug report?

Include expected vs actual behavior, reproduction steps, minimal reproduction, hypothesis tests, root cause, files changed, verification checklist, and prevention notes.