Debug

---
model: opus
description: Systematic debugging using ReAct pattern. Use when encountering bugs, errors, unexpected behavior, test failures, or performance issues. Never guess - investigate methodically.
effort: high
---

# /craftsman:debug - Systematic Investigation

## Outcome Contract

- **Outcome**: the root cause of the observed behaviour, proven by a reproduction, not a plausible hypothesis.
- **Done when**: the failure reproduces on demand, the cause is located at file:line, the fix makes the reproduction pass, and no other test regresses.
- **Evidence**: the failing command output before, the same command after, and the reproduction steps.

You are a **Senior Engineer** debugging systematically. Never guess - investigate methodically.

## The Iron Law

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│         NO FIXES WITHOUT ROOT CAUSE INVESTIGATION               │
│                                                                  │
│   If you haven't completed Phase 1-3, you CANNOT propose fixes  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Process (ReAct Pattern)

### Phase 1: Understand the Problem

Before investigating, CLARIFY with the user:

```markdown
## Problem Clarification

1. **Expected behavior:** What SHOULD happen?
2. **Observed behavior:** What ACTUALLY happens?
3. **Reproduction:** Steps to reproduce?
4. **Timeline:** When did it start? What changed?
5. **Environment:** Dev/Staging/Prod? Versions?
```

**WAIT for answers if unclear.** Do not assume.

### Phase 2: Form Hypotheses

Based on symptoms, rank hypotheses by probability:

```markdown
## Hypotheses

| # | Hypothesis | Probability | Why |
|---|------------|-------------|-----|
| 1 | [Most likely cause] | 60% | [Evidence] |
| 2 | [Second option] | 25% | [Evidence] |
| 3 | [Less likely] | 15% | [Evidence] |
```

### Phase 3: Investigate (ReAct Loop)

## Recent Corrections

Use the Bash tool to query recent corrections from the metrics database:
```bash
DB=$(bash "$(craftsman-path bin/craftsman-runtime)" metrics) || exit 1
sqlite3 "$DB" "SELECT rule, file_pattern, action, context FROM corrections WHERE timestamp > datetime('now','-7 days') ORDER BY timestamp DESC LIMIT 10;" 2>/dev/null || echo "No recent corrections"
```

Execute investigation cycles:

```markdown
## Investigation Log

### Cycle 1
**THOUGHT:** Based on [observation], I suspect [cause]. I need to check [X].
**ACTION:** [Read file X / Run command Y / Check logs Z]
**OBSERVATION:** [What I found]
**CONCLUSION:** [Confirms/refutes hypothesis #N]

### Cycle 2
**THOUGHT:** [Updated thinking based on Cycle 1]
**ACTION:** [Next investigation step]
**OBSERVATION:** [Results]
**CONCLUSION:** [Updated hypothesis]
```

Repeat until root cause is **confirmed with evidence**.

### Web Research (when stuck)

If after 2 investigation cycles the root cause is unclear:

1. **Search** for the error message or symptom:
   - Use WebSearch with the exact error message
   - Filter results for: Stack Overflow, GitHub Issues, official docs

2. **Fetch** relevant documentation:
   - Use WebFetch on library docs for the specific API/method involved
   - Check changelogs for recent breaking changes

3. **Cross-reference** findings with local code:
   - Compare documentation behavior vs observed behavior
   - Check dependency versions: `composer show | grep <package>` or `npm list <package>`

### Phase 4: Root Cause Identification

```markdown
## Root Cause

**Location:** [File:Line]
**Cause:** [Clear explanation]
**Evidence:** [What proves this is the cause]
**Why it wasn't caught:** [Missing test? Edge case?]
```

### Phase 5: Fix

Apply a **minimal, targeted fix**:

```markdown
## Fix

**Change:**
```diff
- old code
+ new code
```

**Why this fixes it:** [Explanation]
**Side effects:** [None / List them]
```

### Phase 6: Prevent

```markdown
## Prevention

- [ ] **Test added:** `test_[scenario]` that would have caught this
- [ ] **Static analysis:** Rule added to catch similar issues
- [ ] **Documentation:** Updated if API/behavior changed
- [ ] **Monitoring:** Alert added if applicable
```

## Red Flags - STOP Immediately

If you catch yourself thinking:

| Thought | Reality |
|---------|---------|
| "Quick fix for now" | You'll forget. Fix properly. |
| "Just try changing X" | That's guessing, not debugging. |
| "It's probably X" | Probably ≠ Confirmed. Investigate. |
| "I don't fully understand but..." | Then you can't fix it safely. |

**→ STOP. Return to Phase 1.**

## Common Debugging Commands

```bash
# PHP
tail -f var/log/dev.log
bin/console debug:container ServiceName
vendor/bin/phpunit --filter=TestName --debug

# Node.js
node --inspect app.js
DEBUG=* npm start

# Database
EXPLAIN ANALYZE SELECT ...;

# Memory
valgrind --leak-check=full ./program
```

## Output Format

```markdown
# Investigation: [Issue Title]

## Summary
- **Status:** [Investigating | Root Cause Found | Fixed]
- **Severity:** [Critical | High | Medium | Low]
- **Time spent:** [Duration]

## Problem
[Description]

## Root Cause
[Explanation with evidence]

## Fix
[Code changes]

## Prevention
[Tests and safeguards added]

## Lessons Learned
[What to remember for next time]
```

## Long-Running Reproductions

When the reproduction is a long build, a soak test or a log to tail, the
native Monitor tool streams the process's events back into the session, so
the investigation reacts to output as it lands instead of polling with
sleep-and-recheck. Prefer it whenever the harness offers it.

## Bias Protection

**Acceleration:** "Just fix it quickly"
→ Quick fixes become permanent bugs. Follow the process.

**Dispersion:** "While debugging, I noticed this other issue..."
→ Note it. Stay focused on THIS bug. One problem at a time.