bug-hunt

What this skill does

# 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:**
- writable `.agents/` output directories; create them explicitly if absent
- 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 `skills/bug-hunt/references/failure-categories.md`.**

**For audits or pre-release sweeps that need more than one pass, route through `skills/bug-hunt/references/audit-fix-rescan-cycle.md` (multi-pass methodology) and use `skills/bug-hunt/references/convergence-criteria.md` to decide when to stop.**

For proactive sweeps that need fresh-eyes rescans, also load [references/multi-pass-bug-hunting.md](references/multi-pass-bug-hunting.md).

For stuck commands, deadlocks, retry storms, blocked subprocesses, or hangs, load [references/deadlock-and-hang-triage.md](references/deadlock-and-hang-triage.md) before changing code.

When the target process is live, hung, or only reproducible under debugger observation, load [references/debugger-attach-triage.md](references/debugger-attach-triage.md) before attaching or changing ptrace/sysctl settings.

## Execution Steps

Given `/bug-hunt <symptom>`:

---

### Step 0: Load Prior Bug Context

Before investigating, check for prior learnings about this area of the codebase:

```bash
if command -v ao &>/dev/null; then
    ao lookup --query "<symptom-keywords> bug patterns" --limit 3 2>/dev/null || true
fi
```

**Apply retrieved knowledge:** If learnings are returned, check each for applicability to the current bug. For applicable learnings (e.g., prior bugs in same area, known fragile patterns), include as investigation leads and cite by filename. Record: `ao metrics cite "<path>" --type applied 2>/dev/null || true`

Prior bug reports, fix patterns, and known fragile areas reduce investigation time.

---

## 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.** Do not skip or skim them.

If the bug can't be reproduced, gather more information before proceeding.

### Step 1.2: Locate the Symptom

Find where the bug manifests:
```bash
# Search for error messages
grep -r "<error-text>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

# Search for function/variable names
grep -r "<relevant-name>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
```

### Step 1.3: Git Archaeology

Find when/how the bug was introduced:

```bash
# When was the file last changed?
git log --oneline -10 -- <file>

# What changed recently?
git diff HEAD~10 -- <file>

# Who changed it and why?
git blame <file> | grep -A2 -B2 "<suspicious-line>"

# Search for related commits
git log --oneline --grep="<keyword>" | head -10
```

### Step 1.4: Trace the Execution Path

**USE THE TASK TOOL** (subagent_type: "Explore") to trace the execution path:
- Find the entry point where the bug manifests
- Trace backward to find where bad data/state originates
- Identify all functions in the path and recent changes to them
- Return: execution path, likely root cause location, responsible changes

### Step 1.5: Identify Root Cause

Based on tracing, identify:
- **What** is wrong (the actual bug)
- **Where** it is (file:line)
- **When** it was introduced (commit)
- **Why** it happens (the logic error)

---

## Phase 2: Pattern Analysis

### Step 2.1: Find Working Examples

Search the codebase for similar functionality that WORKS:
```bash
# Find similar patterns
grep -r "<working-pattern>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
```

### Step 2.2: Compare Against Reference

Identify ALL differences between:
- The broken code
- The working reference

Document each difference.

---

## Phase 3: Hypothesis and Testing

### Step 3.1: Form Single Hypothesis

State your hypothesis clearly:
> "I think X is wrong because Y"

**One hypothesis at a time.** Do not combine multiple guesses.

### Step 3.2: Test with Smallest Change

Make the SMALLEST possible change to test the hypothesis:
- If it works → proceed to Phase 4
- If it fails → record failure, form NEW hypothesis

### Step 3.3: Check Failure Counter

Check failure count per `skills/bug-hunt/references/failure-categories.md`. After 3 countable failures, escalate to architecture review.

---

## Phase 4: Implementation

### Step 4.1: Design the Fix

Before writing code, design the fix:
- What needs to change?
- What are the edge cases?
- Will this fix break anything else?
- Are there tests to update?

### Step 4.2: Create Failing Test (if possible)

Write a test that demonstrates the bug BEFORE fixing it.

### Step 4.3: Implement Single Fix

Fix at the ROOT CAUSE, not at symptoms.

### Step 4.4: Verify Fix

Run the failing test - it should now pass.

If the bug is in a high-complexity function, consider `/refactor` after fix to prevent recurrence.

---

## Audit Mode

When invoked with `--audit`, bug-hunt switches to a proactive sweep. No symptom needed — you're hunting for bugs that haven't been reported yet.

```bash
/bug-hunt --audit cli/internal/goals/     # audit a package
/bug-hunt --audit src/auth/               # audit a directory
/bug-hunt --audit .                        # audit recent changes in repo
```

### Audit Step 1: Scope

Identify target files from the scope argument:

```bash
# Find source files in scope
find <scope> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50
```

If scope is `.` or broad (>50 files), narrow to recently changed files:

```bash
git log --since="2 weeks ago" --name-only --pretty=format: -- <scope> | sort -u | head -30
```

### Audit Step 2: Systematic Read

Read **every file** in scope line by line. For each file, check:

| Category | What to Look For |
|----------|-----------------|
| **Resource Leaks** | Unclosed handles, orphaned processes, missing cleanup/defer |
| **String Safety** | Byte-level truncation of UTF-8, unsanitized input |
| **Dead Code** | Unreachable branches, unused constants, shadowed variables |
| **Hardcoded Values** | Paths, URLs, repo-specific assumptions that won't work elsewhere |
| **Edge Cases** | Empty input, nil/zero values, boundary conditions |
| **Concurrency** | Unprotected shared state, goroutine leaks, missing signal handlers |
| **Error Handling** | Swallowed errors, missing context, wrong error types |

**Key discipline:** Read line by line. Do not skim. The proven methodology (5 bugs found, 0 hypothesis failures) came from careful reading, not heuristic scanning.

**USE THE TASK TOOL** (subagent_type: "Explore") for large scopes — split files across parallel agents.

### Audit Step 3: Classify Findings

For each finding, assign severity:

| Severity | Criteria | Examples |
|----------|----------|---------|
| **HIGH** | Data loss, security, resource leak, proc