bug-hunt-swarm

SKILL.md

Bug Hunt Swarm

Investigate a bug with four read-only sub-agents in parallel, then have the main agent rank the likely causes and recommend the fastest path to prove or fix the issue. This skill is diagnosis-first: do not edit files or implement fixes as part of this workflow.

Step 1: Build the Bug Packet

Start by collecting the smallest useful investigation packet:

Symptom

Expected behavior

Actual behavior

Reproduction steps, if known

Scope of impact

Relevant evidence, such as logs, stack traces, failing tests, screenshots, recent diffs, or environment details

Prefer this source order:

Direct user description

Explicit files, stack traces, logs, tests, or screenshots provided by the user

Current git changes or recent repo history when the bug appears regression-like

The smallest relevant code path or subsystem surrounding the failure

If the bug report is underspecified, infer a minimal problem statement and say what is still unknown.

Before launching sub-agents, read the closest project instructions and relevant docs for the touched area, such as:

AGENTS.md

repo workflow docs

architecture, state, routing, schema, or runtime docs for the affected subsystem

Step 2: Bound the Investigation

Write a short investigation brief for the swarm:

What appears broken

What is not yet proven

What part of the system is most likely involved

What evidence already exists

What kind of proof would count as confirmation

Use read-only evidence gathering where useful:

rg, git diff, git log, git show

reading logs, crash traces, and config

existing test runs or the smallest safe reproduction command

Do not edit files, inject new instrumentation, or implement fixes as part of this skill.

Step 3: Launch Four Read-Only Investigators in Parallel

Launch four sub-agents when the problem is large or ambiguous enough that parallel investigation helps. For a tiny and obvious issue, it is acceptable to investigate locally instead.

For every sub-agent:

give the same bug packet and investigation brief

state that the sub-agent is read-only

do not let the sub-agent edit files, run apply_patch, stage changes, commit, or perform any other state-mutating action

ask for concise investigation output only

ask for: hypothesis, supporting evidence, missing evidence, smallest proof step, and confidence

tell the sub-agent to avoid generic code quality feedback, nits, or speculative guesses without evidence

tell the sub-agent to send findings back to the main agent only

Use these four investigation roles.

Sub-Agent 1: Reproduction and Scope Investigation

Clarify the exact failure shape and its boundaries.

Check for:

The narrowest reliable trigger

Conditions that make the bug appear or disappear

Expected versus actual behavior at the failure boundary

Whether the impact is local, cross-cutting, deterministic, or flaky

This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.

Recommended sub-agent role: reviewer

Sub-Agent 2: Code Path and Failure Seam Investigation

Trace the most likely execution path and identify the seam where behavior diverges.

Check for:

State transitions, lifecycle edges, or ordering problems

Mismatched assumptions between caller and callee

Data-flow or control-flow breaks

The smallest code region most likely responsible for the failure

This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.

Recommended sub-agent role: explorer for broad tracing, or reviewer when a stronger local reasoning pass is more useful

Sub-Agent 3: Recent Change and Regression Investigation

Look for likely regressors in nearby history or changed contracts.

Check for:

Recent diffs that correlate with the symptom

Config, flag, dependency, schema, or migration drift

Partial updates where several entry points should have changed together

Behavior changes that fit the timing of the bug report

This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.

Recommended sub-agent role: reviewer

Sub-Agent 4: Proof Plan and Observability Investigation

Determine the fastest way to confirm or reject the leading hypotheses.

Check for:

The smallest existing test or reproduction that should fail

The most useful current logs, traces, metrics, or assertions

A minimal non-mutating command that could raise confidence quickly

What evidence is missing and how to collect it without broad churn

This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.

Recommended sub-agent role: reviewer

Report only hypotheses that materially improve the odds of finding the real cause. It is better to return two evidence-backed theories than six vague guesses.

Step 4: Synthesize Ranked Hypotheses

The main agent owns synthesis. Treat sub-agent output as raw investigation input, not final output.

Merge and rank the hypotheses:

combine duplicates

discard weak speculation

prefer evidence over elegance

separate likely root causes from mere contributing factors

keep alternate theories only when they remain plausible

Normalize the surviving hypotheses into this shape:

Hypothesis

Supporting evidence

Missing or conflicting evidence

Smallest proof step

Confidence: high, medium, or low

If the evidence is too weak for a real ranking, say so directly and present the leading open questions instead.

Step 5: Output a Clear Diagnosis Path

Present the result in this order:

Most likely root cause

Plausible alternate causes, if any

Fastest proof step

Recommended fix path

Open questions or blockers

When the fix is not yet clear, recommend the next proving step instead of pretending the diagnosis is complete.

When helpful, group actions into:

prove now

fix next

follow up later

Do not implement fixes as part of this skill. The output is a read-only diagnosis with a prioritized path forward.