# Bug Hunt Swarm

Parallel read-only multi-agent root-cause investigation for bugs, regressions, crashes...

- Repository: https://github.com/Dimillian/Skills (4021 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-03-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Dimillian/Skills --skill bug-hunt-swarm -g -a claude-code -y`
Codex: `npx skills add Dimillian/Skills --skill bug-hunt-swarm -g -a codex -y`
Cursor: `npx skills add Dimillian/Skills --skill bug-hunt-swarm -g -a cursor -y`
Gemini CLI: `npx skills add Dimillian/Skills --skill bug-hunt-swarm -g -a gemini-cli -y`

## Description

Parallel read-only multi-agent root-cause investigation for bugs, regressions, crashes, flaky behavior, or unexplained failures. Use when the user asks to investigate a bug, find the root cause, trace a regression, understand why something broke, or wants a ranked diagnosis with the fastest proof path without making code edits.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

1. Symptom
2. Expected behavior
3. Actual behavior
4. Reproduction steps, if known
5. Scope of impact
6. Relevant evidence, such as logs, stack traces, failing tests, screenshots, recent diffs, or environment details

Prefer this source order:

1. Direct user description
2. Explicit files, stack traces, logs, tests, or screenshots provided by the user
3. Current git changes or recent repo history when the bug appears regression-like
4. 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:

1. What appears broken
2. What is not yet proven
3. What part of the system is most likely involved
4. What evidence already exists
5. 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

The rest: https://github.com/Dimillian/Skills/blob/HEAD/bug-hunt-swarm/SKILL.md