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

For failure category taxonomy and the 3-failure rule, read skills/bug-hunt/references/failure-categories.md.

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

Step 5: Write Bug Report

For bug report template, read skills/bug-hunt/references/bug-report-template.md.

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