ranbot-ai Bug Hunt Swarm
When to Use
Use this skill when you need 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...
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