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

Failure Tracking

Track failures by TYPE - not all failures are equal:

root_cause_not_found

fix_failed_tests

design_rejected

execution_timeout

external_dependency

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:

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. 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 to explore the code:

Tool: Task
Parameters:
  subagent_type: "Explore"
  description: "Trace bug execution path"
  prompt: |
    Trace the execution path for: <symptom>

    1. Find the entry point where the bug manifests
    2. Trace backward to find where bad data/state originates
    3. Identify all functions in the path
    4. Look for recent changes to these functions

    Return:
    - Execution path (function call chain)
    - Likely location of root cause
    - Recent changes that might be responsible

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

# Count failures (excluding timeouts and external blockers)
failures=$(bd show <issue-id> --json 2>/dev/null | jq '[.notes[]? | select(startswith("FAILURE:")) | select(contains("root_cause") or contains("fix_failed") or contains("design_rejected"))] | length')

if [[ "$failures" -ge 3 ]]; then
    echo "3+ fix attempts failed. Escalating to architecture review."
    bd update <issue-id> --append-notes "ESCALATION: Architecture review needed after 3 failures" 2>/dev/null
    exit 1
fi

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.

Step 5: Write Bug Report

Write to:

.agents/research/YYYY-MM-DD-bug-<slug>.md

# Bug Report: <Short Description>

**Date:** YYYY-MM-DD
**Severity:** <critical|high|medium|low>
**Status:** <investigating|root-cause-found|fix-designed>

## Symptom
<What the user sees>

## Expected Behavior
<What should happen>

## Reproduction Steps
1. <step 1>
2. <step 2>
3. <observe bug>

## Root Cause Analysis

### Location
- **File:** <path>
- **Line:** <line number>
- **Function:** <function name>

### Cause
<Explanation of what's wrong>

### When Introduced
- **Commit:** <hash>
- **Date:** <date>
- **Author:** <author>

## Proposed Fix

### Changes Required
1. <change 1>
2. <change 2>

### Risks
- <potential risk>

### Tests Needed
- <test to add/update>

## Related
- <related issues or PRs>

Step 6: Report to User

Tell the user:

1. Root cause identified (or not yet)
2. Location of the bug (file:line)
3. Proposed fix
4. Location of bug report
5. Failure count and types encountered
6. Next step: implement fix or gather more info

Key Rules

• Reproduce first - confirm the bug exists
• Use git archaeology - understand history
• Trace systematically - follow the execution path
• Identify root cause - not just symptoms
• Design before fixing - think through the solution
• Document findings - write the bug report

Quick Checks

Common bug patterns to check:

• Off-by-one errors
• Null/undefined handling
• Race conditions
• Type mismatches
• Missing error handling
• State not reset
• Cache issues