Back to Details

bug-hunt-swarm

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Hunt Swarm

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.
通过4个只读sub-agent并行排查Bug，之后由主Agent对可能的原因进行排序，推荐最快的验证或修复路径。该技能优先做诊断：工作流中不允许编辑文件或实现修复方案。

Step 1: Build the Bug Packet

步骤1：构建缺陷排查信息包

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
首先收集最小可用的排查信息包：
  1. 故障现象
  2. 预期行为
  3. 实际行为
  4. 复现步骤（如有）
  5. 影响范围
  6. 相关证据，例如日志、栈追踪、失败的测试用例、截图、最近的diff、环境详情等
信息来源优先顺序：
  1. 用户直接描述
  2. 用户提供的明确文件、栈追踪、日志、测试用例或截图
  3. 当缺陷疑似回归问题时，当前git变更或仓库近期历史记录
  4. 故障相关的最小范围代码路径或子系统
如果缺陷报告信息不完整，先推断出最小问题陈述，并说明仍未知的信息点。
在启动sub-agent前，先阅读项目相关说明和故障涉及领域的相关文档，例如：
  • AGENTS.md
  • 仓库工作流文档
  • 受影响子系统的架构、状态、路由、schema或运行时文档

Step 2: Bound the Investigation

步骤2：划定排查范围

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.
为集群撰写简短的排查说明：
  1. 疑似故障点
  2. 尚未验证的内容
  3. 最可能涉及的系统模块
  4. 已有的证据
  5. 可作为确认依据的证明类型
按需使用只读方式收集证据：
  • rg
    、
    git diff
    、
    git log
    、
    git show
  • 读取日志、崩溃追踪信息和配置
  • 已有的测试运行记录或最小安全复现命令
该技能的执行过程中不允许编辑文件、注入新的监测代码或实现修复方案。

Step 3: Launch Four Read-Only Investigators in Parallel

步骤3：并行启动4个只读排查sub-agent

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.
当问题规模较大或足够模糊，并行排查能提升效率时，启动4个sub-agent。如果是很小且很明显的问题，也可以直接本地排查。
对每个sub-agent：
  • 提供相同的缺陷信息包和排查说明
  • 明确说明sub-agent为只读权限
  • 禁止sub-agent编辑文件、运行
    apply_patch
    、暂存变更、提交代码或执行任何其他会修改状态的操作
  • 仅要求返回简洁的排查结果
  • 要求返回内容包括：假设、支撑证据、缺失证据、最小验证步骤和置信度
  • 告知sub-agent避免给出通用代码质量反馈、无关细节或无证据支撑的推测
  • 告知sub-agent仅将排查结果返回给主Agent
使用以下4个排查角色：

Sub-Agent 1: Reproduction and Scope Investigation

Sub-Agent 1：复现与范围排查

Clarify the exact failure shape and its boundaries.
Check for:
  1. The narrowest reliable trigger
  2. Conditions that make the bug appear or disappear
  3. Expected versus actual behavior at the failure boundary
  4. 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
明确故障的准确形态和边界。
检查内容：
  1. 最小范围的可靠触发条件
  2. 导致缺陷出现或消失的条件
  3. 故障边界处的预期行为与实际行为差异
  4. 影响是局部的、跨模块的、可稳定复现的还是偶现的
该sub-agent为只读权限，严禁编辑文件、应用patch或对工作区做任何其他修改。
推荐sub-agent角色：
reviewer

Sub-Agent 2: Code Path and Failure Seam Investigation

Sub-Agent 2：代码路径与故障断点排查

Trace the most likely execution path and identify the seam where behavior diverges.
Check for:
  1. State transitions, lifecycle edges, or ordering problems
  2. Mismatched assumptions between caller and callee
  3. Data-flow or control-flow breaks
  4. 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
追踪最可能的执行路径，定位行为发生偏离的断点。
检查内容：
  1. 状态转换、生命周期边界或时序问题
  2. 调用方与被调用方之间的假设不匹配
  3. 数据流或控制流中断
  4. 最可能导致故障的最小代码范围
该sub-agent为只读权限，严禁编辑文件、应用patch或对工作区做任何其他修改。
推荐sub-agent角色：大范围追踪时用
explorer
，需要更强的局部推理时用
reviewer

Sub-Agent 3: Recent Change and Regression Investigation

Sub-Agent 3：近期变更与回归排查

Look for likely regressors in nearby history or changed contracts.
Check for:
  1. Recent diffs that correlate with the symptom
  2. Config, flag, dependency, schema, or migration drift
  3. Partial updates where several entry points should have changed together
  4. 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
在近期历史记录或变更的契约中查找可能的回归原因。
检查内容：
  1. 与故障现象相关的近期diff
  2. 配置、开关、依赖、schema或迁移的漂移
  3. 多个入口点本应同步变更但只做了部分更新的情况
  4. 与缺陷报告时间匹配的行为变更
该sub-agent为只读权限，严禁编辑文件、应用patch或对工作区做任何其他修改。
推荐sub-agent角色：
reviewer

Sub-Agent 4: Proof Plan and Observability Investigation

Sub-Agent 4：验证方案与可观测性排查

Determine the fastest way to confirm or reject the leading hypotheses.
Check for:
  1. The smallest existing test or reproduction that should fail
  2. The most useful current logs, traces, metrics, or assertions
  3. A minimal non-mutating command that could raise confidence quickly
  4. 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.
确定可最快确认或排除核心假设的方法。
检查内容：
  1. 应该会失败的最小已有测试用例或复现路径
  2. 最有价值的现有日志、追踪、指标或断言
  3. 可快速提升置信度的最小非修改式命令
  4. 缺失的证据以及无需大规模改动即可收集证据的方法
该sub-agent为只读权限，严禁编辑文件、应用patch或对工作区做任何其他修改。
推荐sub-agent角色：
reviewer
仅返回能显著提升定位到真实根因概率的假设，返回2个有证据支撑的理论远好于6个模糊的猜测。

Step 4: Synthesize Ranked Hypotheses

步骤4：合并并排序排查假设

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:
  1. Hypothesis
  2. Supporting evidence
  3. Missing or conflicting evidence
  4. Smallest proof step
  5. 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.
主Agent负责结果整合，将sub-agent的输出视为原始排查输入，而非最终结果。
合并并对假设排序：
  • 合并重复项
  • 丢弃证据不足的推测
  • 优先考虑证据而非逻辑自洽性
  • 区分可能的根因和仅起到辅助作用的影响因素
  • 仅保留仍然具备合理性的替代假设
将留存的假设整理为以下格式：
  1. 假设
  2. 支撑证据
  3. 缺失或冲突的证据
  4. 最小验证步骤
  5. 置信度：高、中、低
如果证据太薄弱无法进行有效排序，直接说明情况并列出首要的待解决问题。

Step 5: Output a Clear Diagnosis Path

步骤5：输出清晰的诊断路径

Present the result in this order:
  1. Most likely root cause
  2. Plausible alternate causes, if any
  3. Fastest proof step
  4. Recommended fix path
  5. 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.
按以下顺序呈现结果：
  1. 最可能的根因
  2. 合理的替代原因（如有）
  3. 最快验证步骤
  4. 推荐修复路径
  5. 待解决问题或阻碍
如果修复方案尚不明确，推荐下一步的验证步骤，不要假装诊断已经完成。
如有必要，可将行动分为：
  • prove now
    （立即验证）
  • fix next
    （下一步修复）
  • follow up later
    （后续跟进）
该技能不包含修复实现环节，输出仅为只读诊断结果及优先级排序的后续行动路径。