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 — 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 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:

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:

# 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:

# 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:

# 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.

/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:

# 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:

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, pro