/bug-hunt

name: bug-hunt
description: Proactive bug-hunting workflow. Assesses codebase risk through complexity, coverage, and structural analysis, then spawns focused investigators that write reproducing tests to validate suspected bugs. Thoroughness over speed. Advisory only — produces findings and proposes tickets; does not implement fixes.
model: opus

Bug Hunt — Proactive Bug Discovery

Systematically hunts for bugs before they reach users. An assessor analyzes the codebase to identify high-risk hotspots by cross-referencing code complexity, test coverage gaps, and structural risk factors. Focused hunters then deep-dive into each hotspot, writing reproducing tests to validate or invalidate suspected bugs.

**This is deliberately thorough.** Each suspected bug gets a reproducing test — no speculative reports. The goal is confirmed findings with evidence, not a noisy list of maybes.

**Advisory only.** The skill produces findings and proposes tickets; it does not implement fixes. The cognitive seam between "find bug" and "fix bug" is wide enough that mixing them under one workflow degrades both — investigation pressure shouldn't bias the hunters toward bugs they could easily fix, and remediation requires fresh reasoning the hunters aren't currently in. Tickets capture findings durably across that seam and compose with `/implement` and `/implement-project` for remediation. The reproducing tests serve as acceptance criteria — the fix is done when the test passes.

Workflow Overview

┌──────────────────────────────────────────────────────┐
│                  BUG HUNT WORKFLOW                   │
├──────────────────────────────────────────────────────┤
│  1. Determine scope                                  │
│  2. Spawn assessor (risk analysis)                   │
│     └─ Output: ranked hotspot list + coverage map    │
│  3. For each hotspot:                                │
│     └─ Spawn hunter (investigation + repro tests)    │
│     └─ Prior findings passed to subsequent hunters   │
│  4. Synthesize findings                              │
│  5. Present consolidated findings to user            │
│  6. Cut tickets + commit reproducing tests           │
│     (proposed structure; operator-approved)          │
│  7. (If tickets declined) commit reproducing tests   │
│     standalone for the coverage benefit              │
└──────────────────────────────────────────────────────┘

Workflow Details

1. Determine Scope

**Default:** Production code only. Excluded by default:

• Test code (test files, test fixtures, test helpers)
• Dev-only dependencies and tooling
• Generated code, vendored code

Inform the user of these exclusions.

**Ask the user:**

• "What is the scope of the hunt?" (entire codebase, specific module, specific area of concern)
• "Are there areas you're particularly worried about?" (recent changes, complex features, etc.)
• "Anything to skip beyond the defaults?"

User concerns influence prioritization but don't replace systematic analysis.

2. Risk Assessment

**Spawn a `swe-bug-assessor` agent:**

You are the risk assessor for a proactive bug hunt. Your analysis will guide
focused investigators who will deep-dive into the hotspots you identify.

Scope: [entire codebase | user-specified scope]
User concerns: [any areas mentioned, or "none specified"]
Exclusions: [test code, vendored code, generated code, plus any user additions]

Perform your full methodology:
1. Map the codebase — language, framework, structure, entry points
2. Coverage analysis — use instrumented coverage if available, fall back to
   manual inspection
3. Complexity analysis — identify functions with high cognitive complexity
4. Structural risk analysis — error handling gaps, input validation gaps,
   shared mutable state, resource management issues, concurrency risks,
   edge case blindness, consistency gaps
5. Git enrichment (optional) — churn hotspots, recent large changes
6. Cross-reference signals and produce a ranked hotspot list

Focus on hotspots where MULTIPLE signals converge — complex AND untested AND
structurally risky. Single-signal hotspots are lower priority.

Output your full assessment in your standard format.

**When the assessor reports back:** Review the hotspot list. This drives the investigation phase.

3. Focused Investigation — Hunters

**For each hotspot in the assessor's list (ALL priorities), spawn a dedicated `swe-bug-hunter` agent:**

You are a focused bug hunter investigating a specific hotspot.

## YOUR HOTSPOT
Target: [from assessor's report]
Files: [from assessor's report]
Risk signals: [from assessor's report]
Hypothesis: [from assessor's report]
Investigation approach: [from assessor's report]

## PRIOR FINDINGS (if any)
[Findings from previous hunters — confirmed bugs, patterns observed]

## YOUR MISSION
Deep-dive into this hotspot. Systematically probe for bugs. For each
suspected issue, write a reproducing test that encodes the correct expected
behavior.

- If the test FAILS: bug confirmed. Keep the test. Document the finding.
- If the test PASSES: hypothesis invalidated. Evaluate whether the test
  improves coverage:
  - Covers a previously untested path → keep it
  - Redundant with existing tests → delete it

Every confirmed finding must have a reproducing test. No speculative reports.

Note any patterns that might apply to other hotspots.

**Run hunters sequentially, not in parallel.** Each hunter's findings and pattern observations are passed to the next. This enables cross-hotspot pattern detection — if hunter 2 finds that error handling is broken in module A, hunter 5 (investigating module B which shares error-handling utilities) gets that context.

**Pass prior findings to each new hunter.** As findings accumulate, each subsequent hunter receives confirmed bugs and observed patterns from previous investigations.

4. Synthesize Findings

After all hunters have reported, synthesize:

**Cross-cutting analysis:**

• Do c