bmad-investigate

调查

概览

根据现有证据重建正在发生的事情，或某个不熟悉区域的功能。生成一份结构化的案件档案，让另一位工程师能够冷启动接手。在缺陷追踪（症状驱动）与区域探查（无症状）之间持续校准；两端适用同样的纪律。

参数： 工单 ID、日志文件路径、诊断归档、错误消息、代码区域名称、问题描述，或现有案件档案的路径。最后一种形式会恢复先前的调查；其他所有形式都会开启新案件。

输出： {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}。引用输入会被记录；原始内容不会读入父上下文，直到某个结果需要时才读取。

{slug} 在有工单 ID 时就是该工单 ID，否则是与用户商定的简短描述性名称，清洗为小写字母数字加连字符。若在解析后的路径上与现有案件档案冲突，询问是重命名为 slug-YYYY-MM-DD.md 还是恢复现有文件（恢复会路由到结果 0）。

每个结果之后，呈现所了解到的情况，并在继续之前暂停等待用户。

原则

• 证据分级。
  • 已确认。 直接观察到；引用 path:line、日志时间戳或提交哈希。
  • 推断。 从已确认证据逻辑推出；展示推理链。
  • 假设。 看似合理但未经确认；说明什么能确认或反驳它。
• 先立据点。 锚定在一个已确认的证据上，再向外扩展。绝不要从一个理论出发去寻找支持。当证据稀少时，切换到轻证据模式（结果 1 分支）。
• 质疑前提。 用户的描述是假设，不是事实。独立验证；如果证据相矛盾，就指出来。
• 跟随证据，而非叙事。 当证据与工作理论矛盾时，更新理论——绝不要反过来。即使用户深信不疑，也要抵制确认偏误。
• 假设永不删除。 更新状态（未决 / 已确认 / 已反驳）并添加结论。错误的弯路也是交付物的一部分。
• 缺失的证据本身就是一项发现。 记录缺口、它能解决什么，以及如何获取它。
• 尽早写下来。 一旦商定 slug 就初始化案件档案；它是跨中断的持久状态。
• Path:line 引用 使用相对于 CWD 的格式，不带前导 /，以便在 IDE 内嵌终端中可点击。
• 委派纪律。 当某一步需要读取 5 个以上文件或任何超过 10K token 的文件时，委派给只返回结构化 JSON 的子 Agent。引用结果中的 path:line；不要在父上下文中重新读取。
• 并行发起独立操作（多重 grep、多重读取、并行清单）——一条消息，多个工具调用。
• 沟通。 证据优先的语言（“证据显示”、“未确认，需要 X 来验证”）。不要含糊其辞，不要叙事。

激活时

第 1 步：解析工作流块

运行：python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

如果脚本失败，停止并暴露错误。

第 2 步：执行前置步骤

按顺序运行 {workflow.activation_steps_prepend} 中的每个条目。

第 3 步：加载持久事实

将 {workflow.persistent_facts} 中的每个条目视为基础上下文。file: 前缀是 {project-root} 下的路径或 glob（加载内容）；其他条目是逐字事实。

第 4 步：加载配置

加载 {project-root}/_bmad/bmm/config.yaml 并解析 {user_name}、{communication_language}、{document_output_language}、{implementation_artifacts}、{project_knowledge}。如果 {implementation_artifacts} 未解析，回退到 ./investigations/，并在初始化前暴露该回退。

第 5 步：问候

用 {communication_language} 问候 {user_name}。

步骤 6：执行追加步骤

按顺序运行 {workflow.activation_steps_append} 中的每个条目。

激活已完成。如果 activation_steps_prepend 或 activation_steps_append 非空，请在继续之前确认每个条目都已按顺序执行。在所有激活步骤完成之前，不要开始主工作流。

步骤 7：确认并路由

将输入作为引用进行确认（记录路径和 ID；不要读取原始内容）。指向现有案例文件的路径 → 结果 0。否则 → 结果 1。

流程

结果 0：现有案例已加载并呈现

读取案例文件。按顺序呈现：未解决的假设（Status = Open）及其确认/反驳标准；未解决的 待办事项（Status ≠ Done）；缺失证据行；最近的 Conclusion 及其置信度。询问要跟进哪条线索。新 证据会开启一个新的 ## Follow-up: {YYYY-MM-DD} 块（同一天再次进入时追加 #2、#3）。以 上摘要暂停并等待用户；等待指示。

结果 1：范围与据点已确立

确认每种输入形态——仅记录位置、范围、时间窗口；批量读取在结果 2 中进行。

• 问题跟踪器工单。 通过可用的 MCP 工具获取完整详情。
• 诊断归档。 记录路径、文件数量、时间窗口。
• 日志文件或堆栈跟踪。 记录路径和时间窗口；此处仅将用户消息中已存在的堆栈帧纳入 范围。
• 自由文本描述。 逐字记录；视为假设。
• 代码区域名称（无症状）。记录入口点。
• 近期提交区域。 记录提交范围。

如果用户带着假设到来，将其登记为假设 #1。独立寻找据点；用户的假设是据点要验证或反驳的 对象之一。

寻找据点：一条已确认的证据（错误消息、函数名、HTTP 路由、配置参数、测试 用例）。以此为锚点。

在分支之前初始化 {case_file}。 路径为 {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}，其中 {slug} 已替换（slug 和冲突规则见概述）。从 {workflow.case_file_template} 创建文件，并填写 Hand-off Brief （粗略）、Case Info、Problem Statement、初始 Evidence Inventory。

证据稀薄分支。 当无法获取任何已确认证据时：在 Hand-off Brief 中将该案例标记为证据稀薄；用按优先级排序的数据收集项填充 Investigation Backlog；记录"为取得进展，我需要以下之一：……"；暂停并等待用户提供证据或授权结果 2 进行更广泛的扫描。

否则呈现范围、据点、文件路径、拟议方法。以上摘要暂停并等待用户；等待指示。

结果 2：证据边界已映射

勘察现场：跨以下独立类别并行盘点可用证据：诊断归档； 问题跟踪器；版本控制；测试结果；静态分析；源代码。对于任何超过约 10K token 的类别， 委托给子代理，返回 JSON 清单（路径、大小、时间窗口、引用为 path:line 的关键片段）。

将每一项分类为 Available、Partial 或 Missing——Missing 本身就是一项发现。更新 Evidence Inventory 和 Investigation Backlog。以上摘要暂停并等待用户；等待指示。

结果 3：对原因进行严谨推理

• 追踪因果关系。 症状驱动：从症状反向追踪到产生条件和浮现的状态。探索：从输出（返回值、副作用、发送的消息）反向追踪到产生条件。技术相同，锚点不同。
• 重建时间线，交叉参照日志、系统事件、版本控制、用户观察。
• 形成并检验假设。 陈述、识别证实/反驳证据、搜索、评级（已确认 / 已反驳 / 待定）。更新状态。绝不删除。
• 反驳环节。 每当假设趋向已确认，首先主动寻找反驳证据。在 Resolution 中记录该尝试。
• 验证用户的前提。 如果证据相矛盾，明确说明。
• 将发现的路径加入待办列表。 专注于当前线索。

更新已确认发现、推断结论、假设路径、待办列表、时间线。高亮与原始前提的矛盾。以上述回顾暂停等待用户；等待指示。

结果 4：在关键之处完成源代码追踪

在一条消息中作为并行工具调用发出这些首轮扫描：grep 精确错误字符串；glob 受影响目录以查找并行实现；git log 查看近期更改。

然后依次进行：阅读周边代码；沿调用方链追溯；留意语言和进程边界跨越（编译→脚本、IPC、主机→设备、配置流）。

按案例类型精简：

• 探索： I/O 映射（触发器、输出、依赖）；高频词扫描；控制流过滤（分支、循环、错误处理、状态机转换）。
• 症状驱动： 深度评估——根本原因是否可从本地上下文到达，还是需要更广泛的区域模型？呈现升级；绝不悄然扩大范围。简单修复评估——差一错误、缺少空值检查、参数颠倒 → 在报告中给出一行代码建议或草拟 diff；非简单 → 在根本原因区域停止。

调查在诊断处停止；实现不在范围内。更新源代码追踪（错误起源、触发器、条件、相关文件；更广泛时包含区域模型）。以上述回顾暂停等待用户；等待指示。

结果 5：报告完成且交接干净

更新 {case_file}：

• 交接简报 重写为最终形式（3 句话，15 秒阅读）。
• 最终结论 附置信度：高（已确认根本原因，确定性复现），中（推断；轻微不确定性），低（假设；明显数据缺口）。
• 修复方向 在适用时（若多个组合，按机制分类）。
• 诊断步骤 若不确定性仍存在。
• 复现计划 在适用时，或探索案例的验证计划。
• 状态： 进行中 / 已结束 / 因证据受阻。

呈现结论，然后给出具体的后续步骤菜单：简单修复 → bmad-quick-dev；范围/计划调整 → bmad-correct-course；跟踪故事 → bmad-create-story；全新审查 → bmad-code-review。推荐最高价值行动。缓解措施和变通方法仅在明确请求时生成——调查在诊断处停止。如果 {workflow.on_complete} 非空则执行。以上述回顾暂停等待用户；等待指示。

后续迭代

通过在 {case_file} 下新的 ## Follow-up: {YYYY-MM-DD} 块（同日重入用 #2、#3）中追加来继续工作。调查在以下情况完成：

• 根本原因已确认。
• 根本原因已假设且有明显数据缺口。
• 心智模型足以满足用户所述目标（探索案例）。
• 待办列表仅包含需要不可用证据的项目。
• 用户明确结束。