bmad-investigate

BMAD 调查

取证式分诊——规划修复方案，不要实施修复。

此技能会构建一份结构化、按证据分级的调查档案，让接手该事项的人清楚了解已知情况、可疑之处，以及进行任何代码更改前需要核实的具体事项。它会刻意止步于实施之前；每次调查的结果都是一份交接给外部开发工具的故事。

**角色风格：**Mary（业务分析师）阐述用户影响；Winston（架构师）梳理组件拓扑。此技能是一套工作流，而非角色。

---

范围规则（请先阅读）

此技能负责规划。它会读取规划资料和现有代码以收集证据。 它不会编写应用代码、运行测试、执行 lint 或构建，也不会审查差异。 它生成的最后一份产物要么是更新后的规划文档，要么是标记为 status: ready-for-dev 的故事文件。如果你想要“修复 bug”“运行测试套件”或“应用补丁”——请停止。进行调查并移交。

---

输入（先加载这些内容）

来源	原因
bmad-output/project-context.md	项目章程——架构、技术栈、所有权
bmad-output/architecture.md	组件边界、模块职责
bmad-output/prd.md 或 tech-spec.md	出问题的行为应满足的需求
bmad-output/decision-log.md	可能与问题相关的过往决策
用户提供的症状描述	主要输入——出现了什么问题、何时出现、如何出现
用户粘贴的日志／错误消息	用于分级和分析的原始证据
bmad-output/stories/ 中的现有故事文件	检查是否有重复或相关工作

如果 project-context.md 不存在，请先让用户描述技术栈和受影响的部分，再继续。

---

三种意图

如果意图不明确，请询问用户适用哪一种。

• 创建——从头创建新的调查档案。
• 更新——向现有档案添加新证据，并重新排列假设的优先级。
• 验证——根据档案契约检查草稿档案是否完整。

---

工作流——创建

使用 TodoWrite 跟踪这些步骤的进度。

步骤 1——明确症状

开始调查前，确认具体可观察到的情况。询问（或根据上下文推断）：

1. 症状——什么行为不正确？预期行为是什么？
2. 触发条件——何时发生？每次都会发生吗？偶尔发生吗？在负载下发生吗？
3. 范围——哪些用户、环境或配置受到影响？
4. 首次出现时间——问题何时引入或首次被发现？
5. 严重程度——数据丢失、服务中断、用户体验下降，还是外观问题？

将这些记录为“症状摘要”——这是之后所有分级工作的依据。

---

步骤 2——加载上下文

读取上面列出的所有可用输入。提取：

• 受影响的组件——症状涉及哪些模块／服务？ （对照 architecture.md 中的组件职责进行核查。）
• 相关需求——出问题的行为涉及哪些 FR 或 NFR？ （在 prd.md 中搜索相关部分。）
• 近期决策——是否有涉及可疑部分的 ADR 或 decision-log 条目？
• 类似故事——是否有引用相同组件的现有故事文件？

---

第 3 步 — 收集并评定证据

收集所有可用证据。为每项证据指定一个等级：

等级	含义
A	直接观察到、可复现，或经多个独立来源确认。高置信度。
B	来自单一来源、根据日志推断，或看似合理但尚未复现。中等置信度。
C	推测性证据，仅基于代码阅读，或未经直接确认、仅通过模式匹配得出。低置信度。

需要收集的证据类型：

• 错误消息和堆栈跟踪（原样粘贴；若直接来自日志，标记为 A 级）
• 复现步骤（若能稳定复现，标记为 A 级；若间歇性复现，标记为 B 级）
• 通过 Grep/Glob 确定的代码路径（B 级——阅读代码得出的结论属于推断，并非证明）
• 配置或环境差异（除非在两个环境中都得到确认，否则标记为 B 级）
• 历史变更 — 修改过相关部分的近期提交或 PR（未经复现确认时标记为 C 级）
• 用户报告或支持工单（B 级——默认视为外部且不可复现）

使用 Grep 和 Glob 搜索代码库，查找用户提到的错误字符串、函数名或文件路径。阅读代码文件以追踪调用路径。不要运行代码——只阅读代码。

---

第 4 步 — 提出假设

根据所有 A 级和 B 级证据，拟定 2–5 个假设。每个假设都包括：

• 假设 — 简明陈述推测的根本原因。
• 支持证据 — 支持该假设的证据项（注明等级）。
• 反对证据 — 任何与该假设相悖的证据。
• 可信度排名 — 高 / 中 / 低（根据 A 级和 B 级证据的权重得出）。
• 验证步骤 — 开发 Agent 需要执行哪些操作来确认或否定该假设。

按照可信度从高到低排列假设。

---

第 5 步 — 映射疑似组件

针对排名前 2 的假设，列出：

• 组件 — 疑似相关的模块、服务或文件。
• 怀疑原因 — 证据关联（等级 + 描述）。
• 影响范围 — 如果该假设成立，还可能影响哪些内容？
• 置信度 — 根据与该组件关联的最高等级证据得出。

---

第 6 步 — 编写案例文件

填写模板：

${CLAUDE_PLUGIN_ROOT}/skills/bmad-investigate/templates/investigation.template.md

保存到：bmad-output/investigation-<issue-slug>-<date>.md

使用 Write。根据分析填写所有 {{placeholder}}。

---

第 7 步 — 建议规划响应

完成案例文件后，确定规划响应：

选项 A — 创建修复故事： 使用 bmad-epics-and-stories 中的标准故事契约草拟故事文件。 故事的 Dev Notes 必须引用调查案例文件。状态：ready-for-dev。 命名：bmad-output/stories/ 中的 {epic}.{story}.{slug}.story.md。

选项 B — 更新现有待办故事： 如果待办事项中存在相关故事，建议更新其 Dev Notes 和 AC，以纳入调查发现。除非用户要求，否则不要自行编辑故事；说明需要更新哪些内容。

选项 C — 升级至规划阶段： 如果调查发现涉及多个 epic 的系统性问题，建议用户在创建故事之前运行 /bmad-planning-orchestrator:bmad-prd 或 /bmad-planning-orchestrator:bmad-architecture（Update 意图）。

告知用户适用哪个选项以及原因。如果创建修复故事（选项 A），除非用户另有要求，否则现在就起草。

---

第 8 步 — 记录决定

追加到 bmad-output/decision-log.md：

## Investigation: [Issue Slug] — [Date]
- Symptom: [one sentence]
- Primary hypothesis: [one sentence]
- Primary suspected component: [name]
- Case file: bmad-output/investigation-<slug>-<date>.md
- Recommended response: [Option A/B/C + story ID if created]

---

工作流 — 更新

1. 阅读现有案例文件。
2. 询问：有哪些新证据？
3. 添加带等级的新证据项；如果权重发生变化，重新排列假设。
4. 在文件头中递增案例文件版本。
5. 如果主要假设发生变化，在 decision-log 中注明。

---

工作流 — 验证

根据此检查清单检查案例草稿：

• 症状摘要具体且可测试（不含糊）
• 每项证据都有评级（A / B / C）
• 至少列出两个假设
• 每个假设都包含：支持证据、反驳证据、可信度排名、验证步骤
• 疑似组件部分将每个组件与具体证据对应起来
• 已说明建议采取的行动（选项 A / B / C）
• 如果选择选项 A：已提供故事草稿，或明确说明了故事草稿的内容
• 存在决策日志条目

逐项报告通过/未通过。未经要求，不要编辑。

---

证据评级摘要

评级	标签	典型来源
A	已确认	直接日志、可复现的步骤、两个来源相互佐证
B	可能	单一日志、基于代码阅读的推断、间歇性复现、用户报告
C	推测	有依据的猜测、模式匹配、仅未经测试的假设

在案例文件中，绝不要将 C 级提升为 A 级——外部开发 Agent 在开始前需要知道哪些内容确凿，哪些只是猜测。

---

子 Agent 策略

对于涉及多个疑似组件的大规模调查，分派多个只读 Agent 并行处理：

Agent 1 — 证据收集者

Read the investigation brief at bmad-output/investigation-scratch/brief.md.
Search the codebase with Grep/Glob for error strings, function names, and file
paths listed. Collect stack-trace context. Write findings (verbatim excerpts +
file paths + line numbers) to bmad-output/investigation-scratch/evidence.md.
Do NOT modify any source files. Grade each item A/B/C.

Agent 2 — 组件映射者

Read bmad-output/architecture.md and the brief at
bmad-output/investigation-scratch/brief.md. For each suspected component,
extract its responsibilities, dependencies, and API contracts.
Write findings to bmad-output/investigation-scratch/components.md.

Agent 完成后，使用模板将 evidence.md + components.md 综合整理到最终案例文件中。综合整理后删除临时文件。

---

参考资料

• templates/investigation.template.md
• bmad-output/decision-log.md — 线程式决策记录
• bmad-output/project-context.md — 项目章程
• /bmad-planning-orchestrator:bmad-epics-and-stories — 创建修复故事
• /bmad-planning-orchestrator:bmad-readiness-check — 如果调查发现系统性的规划缺口，且这些缺口会导致修复故事无法安全交接，则使用此项

---

BMAD Planning & Orchestrator 插件的一部分——一个用于 BMAD Method 的 Claude Code 脚手架，由 BMAD Code Organization 开发（https://github.com/bmad-code-org/BMAD-METHOD）。贯彻 bmad-investigate 的精神。所有方法论贡献均归 BMAD Code Organization 所有。