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?
Building a Feedback Loop
This is the most important step. If you have a fast, deterministic, agent-runnable pass/fail signal, you will find the cause. If you don't, no amount of code-staring will save you. Spend disproportionate effort here.
Techniques — try in roughly this order:
- Failing test at whatever seam reaches the bug (unit, integration, e2e)
- Curl / HTTP script against a running dev server
- CLI invocation with fixture input, diffing stdout against known-good output
- Headless browser script (Playwright/Puppeteer) — drives UI, asserts on DOM/console
- Replay captured trace — save a real request/payload to disk, replay through the code path
- Throwaway harness — minimal subset of system that exercises the bug path
- Property/fuzz loop — if "sometimes wrong output", run 1000 random inputs
- Bisection harness — automate
git bisect run between known-good and known-bad
- Differential loop — run same input through old vs new version, diff outputs
Iterate on the loop: Can you make it faster? Sharper signal? More deterministic?
If you cannot build a loop: Stop and say so. List what you tried. Ask for: captured artifacts (logs, HAR file), environment access, or permission to add temporary instrumentation.
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
- [ ] **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
For each hypothesis, record: Hypothesis (what's wrong) → Test (how to verify) → Result → 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 |
Required Action |
| "The fix is obvious" |
Obvious fixes mask root causes |
Form a hypothesis and verify before changing code |
| "It's probably X" |
"Probably" isn't evidence |
Test the hypothesis — name it, design a test, run it |
| "This is too simple to debug formally" |
Simple bugs waste the most time undiagnosed |
Follow Phase 1 — reproduce, isolate, then fix |
| "Logs look clean" |
You didn't add targeted logging |
Add debug logging at the suspected point |
| "I've tried 3 things, might as well try a 4th" |
Stacking guesses compounds confusion |
STOP. Return to Phase 1. Re-analyze with new info |
| "It works now" |
If you don't know why, it will break again |
Explain WHY it works and what changed |
Red Flags - STOP and Re-Assess
If you catch yourself skipping reproduction ("I know what's wrong") or testing multiple hypotheses at once — STOP. Return to Phase 1.
Debug Report Format
## 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]
1---2name: debug3description: 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.4---56# Debug Mode78Systematic bug investigation and resolution.910## Core Approach1112> "Don't guess. Form hypotheses. Test them."1314## The 4-Phase Process1516### Phase 1: Assessment 🔍1718**Goal**: Understand and reproduce1920- What is the expected behavior?21- What is the actual behavior?22- Can you reliably reproduce?23- What changed recently?2425**Key Questions**:2627- When did this start happening?28- Does it happen consistently or intermittently?29- What are the exact inputs that trigger it?30- What error messages or symptoms appear?3132#### Building a Feedback Loop3334**This is the most important step.** If you have a fast, deterministic, agent-runnable pass/fail signal, you will find the cause. If you don't, no amount of code-staring will save you. Spend disproportionate effort here.3536**Techniques — try in roughly this order:**37381. **Failing test** at whatever seam reaches the bug (unit, integration, e2e)392. **Curl / HTTP script** against a running dev server403. **CLI invocation** with fixture input, diffing stdout against known-good output414. **Headless browser script** (Playwright/Puppeteer) — drives UI, asserts on DOM/console425. **Replay captured trace** — save a real request/payload to disk, replay through the code path436. **Throwaway harness** — minimal subset of system that exercises the bug path447. **Property/fuzz loop** — if "sometimes wrong output", run 1000 random inputs458. **Bisection harness** — automate `git bisect run` between known-good and known-bad469. **Differential loop** — run same input through old vs new version, diff outputs4748**Iterate on the loop:** Can you make it faster? Sharper signal? More deterministic?4950**If you cannot build a loop:** Stop and say so. List what you tried. Ask for: captured artifacts (logs, HAR file), environment access, or permission to add temporary instrumentation.5152### Phase 2: Investigation 🔬5354**Goal**: Isolate and trace5556- Trace execution from entry point57- Identify where expected diverges from actual58- Form hypotheses about root cause59- Test hypotheses systematically6061**Techniques**:6263- Add strategic logging/prints64- Use debugger breakpoints65- Simplify inputs to minimal reproduction66- Check boundary conditions6768### Phase 3: Resolution 🔧6970**Goal**: Fix minimally and verify7172- Implement the smallest fix that addresses root cause73- Don't fix symptoms, fix the disease74- Add regression test75- Verify fix doesn't break other things7677**If fix doesn't work:**7879- Count: How many fixes attempted?80- If < 3: Return to Phase 1, re-analyze with new information81- If ≥ 3: STOP. Question your understanding of the system.8283### Phase 4: Quality ✅8485**Goal**: Prevent recurrence8687- Add test covering the bug88- Document if the cause was non-obvious89- Consider if similar bugs exist elsewhere90- Clean up debug code9192## Debugging Checklist9394```markdown95- [ ] **Reproduced**: Can trigger bug consistently96- [ ] **Isolated**: Know which component is failing97- [ ] **Root Cause**: Understand WHY it fails98- [ ] **Fixed**: Minimal change addresses cause99- [ ] **Tested**: Regression test added100- [ ] **Clean**: Debug code removed101```102103## Hypothesis Template104105For each hypothesis, record: **Hypothesis** (what's wrong) → **Test** (how to verify) → **Result** → **Conclusion** (confirmed/rejected/needs more info).106107## Common Root Causes108109| Symptom | Often Caused By |110| -------------------------- | --------------------------------------------- |111| Works locally, fails in CI | Environment differences, missing deps |112| Intermittent failure | Race condition, timing, external dependency |113| Wrong output | Logic error, wrong variable, off-by-one |114| Crash/exception | Null/None access, type mismatch, missing data |115| Performance issue | N+1 queries, missing index, memory leak |116117## Rationalization Prevention118119| Excuse | Reality | Required Action |120| ---------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- |121| "The fix is obvious" | Obvious fixes mask root causes | Form a hypothesis and verify before changing code |122| "It's probably X" | "Probably" isn't evidence | Test the hypothesis — name it, design a test, run it |123| "This is too simple to debug formally" | Simple bugs waste the most time undiagnosed | Follow Phase 1 — reproduce, isolate, then fix |124| "Logs look clean" | You didn't add targeted logging | Add debug logging at the suspected point |125| "I've tried 3 things, might as well try a 4th" | Stacking guesses compounds confusion | STOP. Return to Phase 1. Re-analyze with new info |126| "It works now" | If you don't know why, it will break again | Explain WHY it works and what changed |127128## Red Flags - STOP and Re-Assess129130If you catch yourself skipping reproduction ("I know what's wrong") or testing multiple hypotheses at once — STOP. Return to Phase 1.131132## Debug Report Format133134```markdown135## Debug Report136137### Bug Summary138139- **Expected**: [what should happen]140- **Actual**: [what happens instead]141- **Severity**: [critical/high/medium/low]142143### Reproduction1441451. [Step to reproduce]1462. [Step to reproduce]1473. [Observe bug]148149**Minimal reproduction**: [simplest case that triggers bug]150151### Investigation152153| Hypothesis | Test | Result |154| ---------- | -------------- | -------------------------- |155| [theory] | [what I tried] | ✅ Confirmed / ❌ Rejected |156157### Root Cause158159[What's actually wrong and why]160161### Fix Applied162163- **File**: `path/to/file.py`164- **Change**: [what was modified]165- **Why**: [how this fixes the root cause]166167### Verification168169- [ ] Bug no longer reproduces170- [ ] Existing tests pass171- [ ] Regression test added: `test_name`172- [ ] No debug code left behind173174### Prevention175176[How to prevent similar bugs in the future]177```
mcouthon