bug-hunt

# Bug Hunt Skill

> **Quick Ref:** 4-phase investigation (Root Cause → Pattern → Hypothesis → Fix). Output: `.agents/research/YYYY-MM-DD-bug-*.md`

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

Systematic investigation to find root cause and design a complete fix.

**Requires:**
- session-start.sh has executed (creates `.agents/` directories for output)
- bd CLI (beads) for issue tracking if creating follow-up issues

## The 4-Phase Structure

| Phase | Focus | Output |
|-------|-------|--------|
| **1. Root Cause** | Find the actual bug location | file:line, commit |
| **2. Pattern** | Compare against working examples | Differences identified |
| **3. Hypothesis** | Form and test single hypothesis | Pass/fail for each |
| **4. Implementation** | Fix at root, not symptoms | Verified fix |

## Failure Tracking

**Track failures by TYPE - not all failures are equal:**

| Failure Type | Counts Toward Limit? | Action |
|--------------|----------------------|--------|
| `root_cause_not_found` | YES | Re-investigate from Phase 1 |
| `fix_failed_tests` | YES | New hypothesis in Phase 3 |
| `design_rejected` | YES | Rethink approach |
| `execution_timeout` | NO (reset counter) | Retry same approach |
| `external_dependency` | NO (escalate) | Report blocker |

**The 3-Failure Rule:**
- Count only `root_cause_not_found`, `fix_failed_tests`, `design_rejected`
- After 3 such failures: **STOP and question architecture**
- Output: "3+ fix attempts failed. Escalating to architecture review."
- Do NOT count timeouts or external blockers toward limit

**Track in issue notes:**
```bash
bd update <issue-id> --append-notes "FAILURE: <type> at $(date -Iseconds) - <reason>" 2>/dev/null
```

## Execution Steps

Given `/bug-hunt <symptom>`:

---

## Phase 1: Root Cause Investigation

### Step 1.1: Confirm the Bug

First, reproduce the issue:
- What's the expected behavior?
- What's the actual behavior?
- Can you reproduce it consistently?

**Read error messages carefully.**