bug-huntlisted

# 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 — or proactive audit to find hidden bugs before they bite. **Requires:** - session-start.sh has executed (creates `.agents/` directories for output) - bd CLI (beads) for issue tracking if creating follow-up issues ## Modes | Mode | Invocation | When | |------|------------|------| | **Investigation** | `$bug-hunt <symptom>` | You have a known bug or failure | | **Audit** | `$bug-hunt --audit <scope>` | Proactive sweep for hidden bugs | Investigation mode uses the 4-phase structure below. Audit mode uses systematic read-and-classify — see [Audit Mode](#audit-mode). --- ## The 4-Phase Structure (Investigation Mode) | 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 | **For failure category taxonomy and the 3-failure rule, read `references/failure-categories.md`.** **For audits or pre-release sweeps that need more than one pass, route through `references/audit-fix-rescan-cycle.md` (multi-pass methodolog