在排查 bug、回归、崩溃或偶发故障时…

当你需要在不改代码的前提下，对 bug 或回归做多角度并行根因调查并输出可验证的诊断路径时使用。

适用场景

解决思路

1. 构建 Bug Packet：收集最小可用的调查信息包，包括症状、期望行为、实际行为、已知复现步骤、影响范围，以及相关证据（日志、堆栈、失败测试、截图、近期 diff、环境细节）。
2. 按来源优先级取材：1) 用户直接描述；2) 用户提供的文件、堆栈、日志、测试或截图；3) 当 bug 像回归时，查看当前 git 变更或近期仓库历史；4) 失败点周围最小的相关代码路径或子系统。
3. 如果 bug 报告信息不足，推断一个最小问题陈述，并明确说明仍未知的部分。
4. 在启动子代理前，阅读受影响区域最近的项目说明和相关文档，例如 `AGENTS.md`、仓库工作流文档，以及受影响子系统的架构、状态、路由、schema 或运行时文档。
5. 划定调查边界：为 swarm 写一份简短调查简报，说明：1) 什么看起来坏了；2) 什么尚未被证实；3) 系统哪部分最可能相关；4) 已有什么证据；5) 什么样的证明才算确认。
6. 使用只读证据收集手段：`rg`、`git diff`、`git log`、`git show`，阅读日志、崩溃堆栈和配置，运行已有测试或最小的安全复现命令。
7. 不要编辑文件、注入新埋点或实现修复；本技能以诊断为先。
8. 当问题足够大或模糊、并行调查有帮助时，启动四个子代理；对于很小且明显的问题，可以改为本地调查。
9. 对每个子代理：给相同的 bug packet 和调查简报；声明子代理是只读的；不允许编辑文件、运行 `apply_patch`、暂存变更、提交或执行任何其他改变状态的操作；只要求简洁的调查输出；要求给出假设、支持证据、缺失证据、最小证明步骤和置信度；告诉子代理避免泛泛的代码质量反馈、吹毛求疵或无证据的猜测；告诉子代理只把发现回传给主代理。
10. 子代理 1：复现与范围调查——弄清确切的失败形态及其边界。检查：1) 最窄的可靠触发条件；2) 使 bug 出现或消失的条件；3) 失败边界处的期望行为与实际行为；4) 影响是局部的、横切的、确定性的还是偶发的。该子代理只读，不得编辑文件、应用补丁或做任何其他工作区变更。推荐子代理角色：`reviewer`。
11. 子代理 2：代码路径与失败接缝调查——追踪最可能的执行路径，找出行为发生分歧的接缝。检查：1) 状态转换、生命周期边界或顺序问题；2) 调用方与被调用方之间的假设不匹配；3) 数据流或控制流断裂；4) 最可能对失败负责的最小代码区域。该子代理只读，不得编辑文件、应用补丁或做任何其他工作区变更。推荐子代理角色：广泛追踪用 `explorer`，需要更强的局部推理时用 `reviewer`。
12. 子代理 3：近期变更与回归调查——在附近历史或已变更契约中寻找可能的回归源。检查：1) 与症状相关的近期 diff；2) 配置、开关、依赖、schema 或迁移漂移；3) 本应一起修改的多个入口点只改了部分；4) 与 bug 报告时间吻合的行为变更。该子代理只读，不得编辑文件、应用补丁或做任何其他工作区变更。推荐子代理角色：`reviewer`。
13. 子代理 4：证明计划与可观测性调查——确定确认或排除主要假设的最快方式。检查：1) 最小的、应当失败的现有测试或复现；2) 当前最有用的日志、trace、指标或断言；3) 一个能快速提升置信度的最小非变更命令；4) 缺失什么证据，以及如何在不引起大范围改动的情况下收集它。该子代理只读，不得编辑文件、应用补丁或做任何其他工作区变更。推荐子代理角色：`reviewer`。
14. 只报告能实质性提高找到真正原因概率的假设；返回两个有证据支持的理论，好过六个模糊猜测。
15. 主代理负责综合：把子代理输出当作原始调查输入而非最终输出。合并并排序假设：合并重复项、丢弃弱猜测、偏好证据而非优雅、把可能的根因与仅仅是促成因素分开、只在替代理论仍合理时保留它。
16. 把存活的假设规范化为：1) 假设；2) 支持证据；3) 缺失或冲突证据；4) 最小证明步骤；5) 置信度：高、中或低。
17. 如果证据太弱、无法真正排序，直接说明，并改为给出主要的开放问题。
18. 按以下顺序输出清晰诊断路径：1) 最可能的根因；2) 合理的替代原因（如有）；3) 最快的证明步骤；4) 建议的修复路径；5) 开放问题或阻塞项。
19. 当修复尚不明确时，建议下一步证明步骤，而不是假装诊断已完成。
20. 在有用时，把行动分组为：`prove now`、`fix next`、`follow up later`。
21. 不要在本技能中实现修复；输出是只读诊断，附带按优先级排列的前进路径。

适用边界 · 注意事项

• 问题很小且明显，不需要并行调查时。
• 需要直接编辑代码、注入埋点或实现修复时（本技能只做只读诊断）。
• bug 报告过于模糊且无法推断出最小问题陈述时，应先补充信息而不是启动 swarm。