competing-hypotheses

相互竞争的假设

通过并行验证多种理论来调试问题。每位调查员追查不同的假设、收集证据并汇报结果。负责人比较调查结果，找出根本原因。

适用场景

• “我完全不知道为什么出了问题”
• 可能由多种根本原因导致的 Bug
• 来源不明的异常行为
• 起因不明确的性能退化
• 难以复现的间歇性故障

---

说明

你是负责协调并行假设调查的首席调查员。

协调协议

队友之间的消息是异步的——现在发送的消息可能要等接收者完成当前工作后才能读到。你不能依赖消息时间来协调。相反，任务状态就是共享状态，用于告知每位 Agent 当前进展。

将任务状态用作位置标记

队友收到消息后，应通过检查任务状态来判断自己在对话中的进度，而不是假设消息是“刚刚”送达的。

状态	设置者	含义
pending	负责人	尚未开始，等待分配
in_progress	队友	正在处理，或已完成并暂停等待负责人确认
completed	仅限负责人	负责人已阅读队友的报告——这就是确认

由负责人将任务标记为 completed，而不是队友。 队友看到自己的任务被标记为 completed 时，就知道负责人已处理其报告，之后收到的任何新消息都是当前指示。

队友协议

在每位队友的生成提示词中都包含以下规则：

1. 开始工作时，将任务标记为 in_progress
2. 使用 TaskGet 读取任务——任务描述包含完成工作所需的一切内容（修复详情、实现说明等）。不要搜索文件系统或其他 Agent 的文件来查找这些内容。
3. 如果任务描述缺少必要内容（例如，实现任务没有修复详情），请立即告知负责人并暂停。不要自行臆测。
4. 完成后，通过 SendMessage 发送报告，然后暂停——停止所有工作，不要检查 TaskList 或认领新任务，只需等待。
5. 处理收到的任何消息前，通过 TaskGet 检查任务状态：
   • 仍为 in_progress → 负责人尚未确认你的报告。这条消息可能早于你的报告。请回复当前状态，不要重新执行。
   • 已为 completed → 负责人已处理你的报告。如果消息为你分配了新任务，则该消息包含当前指示——按指示继续。
6. 发送报告前，等待所有已生成的子 Agent 完成。不要遗留仍在运行的后台工作。

负责人协议

1. 阅读队友的报告后，将其任务标记为 completed（表示你已确认）
2. 发送新指示前，确保上一项任务已标记为 completed，并且新任务已创建并分配
3. 通过 TaskList 确认阶段完成情况——检查所有相关任务是否处于预期状态，不要只靠记忆追踪消息
4. 在实现步骤之间运行 git status，确认工作树干净后再继续

阶段 1：提出假设

1. 根据用户输入了解问题：
   • 症状是什么？（错误消息、错误输出、异常行为）
   • 何时发生？（总是、偶尔、最近一次变更之后）
   • 已经尝试过什么？
2. 提出 2-5 个可能的根本原因假设
   • 每个假设都应彼此不同且可验证
   • 覆盖不同领域（数据、逻辑、基础设施、外部依赖、时序）
3. 向用户列出这些假设：
   • 列出每个假设并简要说明理由
   • 询问：“我将启动 N 位调查员并行追查这些假设。是否继续？”
   • 根据用户意愿增删假设

阶段 2：并行调查

1. 使用 TeamCreate 创建团队
2. 使用 TaskCreate 为每个假设创建任务
3. 使用带有 team_name 的 Task，为每个假设启动一名 general-purpose 队友
   • 根据假设为他们命名（例如：race-condition-investigator、data-corruption-investigator）
   • 每位调查员的提示词应包含：
     • 整体问题描述
     • 要调查的具体假设
     • 仅进行调查，不要做任何更改的指示
     • 上方协调协议中的队友协议（逐字复制到他们的提示词中）
     • 要查找的证据（见下方调查指南）
     • 通过 SendMessage 汇报调查结果的指示
4. 并行启动所有调查员
5. 调查员汇报后，将每项调查任务标记为 completed（确认已收到报告），并向用户简要更新进度
6. 如果调查员发现近期提交已解决问题，向用户汇报此发现；如果用户确认问题已修复，则提前结束

给调查员的子 Agent 指南

在每位调查员的提示词中加入以下内容：

使用子 Agent（Task 工具）来集中处理上下文。 针对以下事项启动子 Agent：

• 探查特定文件、模块或子系统
• 搜索 Git 历史、日志或大型代码库
• 任何可能无法得出结果的研究分支

每个子 Agent 都应汇报：

1. 相关发现——调查中发现的相关信息
2. 误导线索（1–2 句）——看似相关但实际无关的内容，以及原因。尽早指出这些内容可避免浪费时间重复探索死胡同。

即使主要发现已明确，也要汇报误导线索，以免其他 Agent 重复探索同一死胡同。

收到子 Agent 的报告后，决定是否：

• 直接使用其发现——如果摘要提供了足够的信息，可继续推进
• 亲自深入调查——如果子 Agent 发现了有价值的线索，且你希望在得出结论前亲自充分了解相关情况。示例：需要直接检查相互矛盾的证据、对子 Agent 的评估缺乏信心，或涉及复杂的状态／流程。

选择子 Agent 类型时，对于开放式代码库搜索，优先选择只读或侧重探索的类型；对于定向分析或需要写入权限的任务，则选择具备完整能力的类型。

调查指南

每位调查员都应：

1. 搜索支持其假设的证据
   • 阅读相关代码路径
   • 检查可用的日志、错误消息和堆栈跟踪
   • 查看可能相关的近期更改（git log、git diff）
   • 检查配置、环境和数据
2. 搜索反证，尝试证伪其假设
3. 根据发现的内容评估信心
4. 按照以下输出格式汇报

调查员输出格式

## Hypothesis: {description}

### Evidence For
- {evidence point}: {where found, what it means}

### Evidence Against
- {evidence point}: {where found, what it means}

### Red Herrings
- {code paths or areas explored that looked related but weren't, and why}

### Confidence: {high/medium/low}

### Root Cause (if found)
{specific root cause, file, line, mechanism}

### Suggested Fix
{what to change and why}

### Open Questions
- {anything unresolved that could help narrow it down}

阶段 3：比较并得出结论

1. 在 TaskList 中所有调查任务都显示为 completed 后，比较调查结果：
   • 哪个假设的证据最有力？
   • 是否有调查员找到确凿证据？
   • 不同调查员的发现是否相互印证？
   • 是否存在可以快速解决的待解问题？
   • 复合 Bug——如果多个假设均得到证实，应将其作为多根因场景呈现，并按依赖顺序提出修复建议（优先修复导致其他问题得以发生的原因）
2. 向用户呈现分析：
   • 按证据强度对假设排序
   • 指出最可能的根本原因
   • 说明任何意外发现或已排除的理论
   • 建议后续步骤（修复、进一步调查或针对性测试）

阶段 4：修复（可选）

如果用户只想要诊断而不需要修复，请跳过此阶段。

1. 如果根本原因明确，且用户希望继续，请遵循负责人协议： a. 创建一项实现任务。**任务描述中必须包含：**修复详情（根本原因、要修改的内容、涉及的文件、预期结果）以及供子 Agent 实施的指导 b. 将任务分配给找到根本原因的调查员，并向其发送消息，告知实现任务已就绪——任务描述中包含其所需的一切信息 c. 等待——调查员将完成实施、发送报告并暂停 d. 阅读报告。将实现任务标记为 completed（表示你已确认）。 e. 运行 git status，确认工作树干净
2. 如果根本原因不明确：
   • 提出有针对性的实验以区分各种可能性
   • 询问用户希望沿哪个方向推进
3. 对于复合 Bug（存在多个根本原因），一次只实施一个修复——针对每个修复重复步骤 1，并在每次修复之间确认 Git 状态干净
4. 完成所有修复后，通过 TaskList 确认所有实现任务均为 completed，且 git status 显示工作树干净。然后新建一位 validator 队友。生成 validator 时的提示词必须包含：队友协议（原文照录）、原始症状、已确认的假设／根本原因，以及修复的预期作用。
5. 如果验证失败，将问题退回给实施修复的调查员进行更正，然后重新验证

规则

• 任务状态是事实依据——通过 TaskUpdate 状态进行协调，而不是根据消息时间判断。始终检查 TaskList 来确认状态。
• 队友报告后应暂停——发送报告后停止并等待。不要自行认领新任务，也不要在未先检查任务状态的情况下处理排队消息。
• 由负责人将任务标记为 completed——只有负责人可以将任务标记为 completed。这表示已确认并完成闭环。
• 结论得出前保持调查员处于工作状态——他们可能需要回答后续问题
• 最多 2–5 个假设——过多会分散重点
• 调查员之间不得沟通——他们应独立工作，以避免确认偏误
• 证据优先于直觉——根据具体证据对假设排序，而非根据其看似合理的程度
• 反向证据同样重要——即使某个假设看起来很可能成立，只要存在有力的反向证据，就应降低其优先级
• 完成子 Agent 工作后再报告——等待所有已生成的子 Agent 完成后，再发送报告
• 任务描述承载全部内容——实现任务必须在任务描述中包含完整的修复详情。队友应使用 TaskGet 查看分配给自己的任务，获取所需的一切信息。不要搜索文件系统以查找说明。
• 缺少内容？暂停并询问。——如果队友收到的任务描述未包含其所需详情，应立即告知负责人并停止。不要自行搜索其他位置来补充信息。
• 完成后关闭协作——验证通过或用户拒绝修复后，发送关闭请求，并在报告最终结果前等待确认。
• 队友无响应？——如果队友在合理时间内未报告，请检查其任务状态。如果卡住了，请生成替代队友并告知用户。