bug-investigator

Bug 调查员

捆绑运行时

执行下方的 CLI 命令之前，将开头的 SSF 替换为 node "<plugin-root>/scripts/spec-superflow.mjs"；<plugin-root> 是此文件上两级目录的绝对路径。切勿直接运行 SSF，也不要调用 PATH 中的 ssf。

核心原则： 先查明根本原因，再尝试修复。只修复症状必然失败。

新的直接／计划变更

调查时无需经历阶段转换或维护单独的调试日志：复现问题、追踪根本原因、进行一次有针对性的修复并验证。将有用的失败证据保留在现有进度记录中。同一未解决问题连续失败 3 次时，应作出决策；无关发现不共用失败次数限额。无需任务手册或子 Agent。以下详细的旧版流程适用于已有的调试状态，或需要该流程的调查。

铁律

未先调查根本原因，不得修复。若尚未完成阶段 1，就不能提出修复方案。

适用场景

适用于任何技术问题：测试失败、Bug、行为异常、性能问题、构建失败、集成问题。尤其适用于时间紧迫、“快速修一下”看似显而易见、已经尝试过多种修复方案，或你并未完全理解问题的情况。

不要因为问题“看起来简单”或你“赶时间”就跳过——系统化调试比反复试错更快。

四个阶段

完成每个阶段后，才能进入下一阶段。

阶段 1：调查根本原因

1. 仔细阅读错误消息：堆栈跟踪、行号、文件路径、错误代码——其中往往包含确切的解决方案
2. 稳定复现问题：每次都能按相同步骤复现吗？如果不能复现 → 收集更多数据，不要猜测
3. 检查近期变更：git diff、近期提交、新依赖、配置变更、环境差异
4. 多组件系统：在各组件边界添加诊断插桩。记录每一层的输入和输出。运行一次收集证据，然后分析哪个组件出现故障
5. 追踪数据流：逆向追踪——错误值从何而来？持续向上追踪，直到找到源头。在源头修复，而不是修复症状

阶段 2：模式分析

1. 在同一代码库中查找类似代码的正常工作示例
2. 对照参考实现——完整阅读参考实现
3. 找出正常代码和故障代码之间的所有差异，无论多么细微
4. 了解依赖项：其他组件、设置、配置、环境和前提假设

阶段 3：提出假设并测试

采用科学方法：提出单一假设（“我认为 X 是根本原因，因为 Y”），通过尽可能小的变更进行测试（一次只改变一个变量），并在继续前验证。如果无效，就提出新的假设——不要叠加更多修复方案。不知道时，应如实说明并寻求帮助。

阶段 4：实施

1. 创建失败测试用例——尽可能简单地复现问题，并在可行时自动化。遵循 build-executor 中的 TDD 规则
2. 实施单一修复——解决根本原因，每次只做一项变更，不要顺手改进其他内容
3. 验证修复——测试通过了吗？没有引入回归问题吗？问题解决了吗？
4. 如果修复无效：统计尝试次数。少于 3 次 → 返回阶段 1。≥ 3 次 → 停止并质疑架构（DP-5）

DP-5：调试升级（失败 3 次以上）

修复失败 3 次以上，说明存在架构问题。每次修复都在其他地方引发新问题，说明架构有误。

每次修复失败后，都要将失败输出保存在变更目录中的一个实体文件里，然后记录这次独立尝试：

Full 和 legacy Hotfix 在运行此命令前，必须有当前有效的执行计划；如有需要，使用 SSF execution recommend 和 SSF execution plan 创建计划。Quick、Tweak、lightweight 和 direct Hotfix 保持无需计划的约定：有效的工作流收据可授权调试，台账会将尝试与该收据以及当前工作流、制品和契约哈希绑定。若缺少收据、收据已被替换，或必需的计划已过期，调试命令会拒绝执行。

SSF debug attempt record <change-dir> \
  --id <unique-attempt-id> \
  --summary "<what was tried and why it failed>" \
  --evidence <change-local-failure-log>

使用 SSF debug attempt show <change-dir> --json 展示完整的尝试台账。Wave Review 修复失败属于独立证据，绝不计为调试尝试。

至少进行 3 次有独立证据支持的尝试后，停止操作，并与用户讨论架构决策。只有在用户明确选择后，才能记录 DP-5：

SSF debug escalate <change-dir> \
  --decision <continue|abandon> \
  --reason "<user-confirmed decision>" \
  --confirm

绝不要通过原始的 SSF state set 写入 dp_5_*；这些字段受调试台账保护。如果用户选择 abandon，只有在记录受保护的 DP-5 收据后，才能将状态转换为 abandoned。

危险信号——返回阶段 1

“先快速修复，之后再调查”/“就试着改一下 X”/“跳过测试，我会手动验证”/“可能是 X，我来修一下”/“我不太明白，但这样或许行得通”/“再尝试修复一次”（已尝试 2 次以上）/在追踪数据流之前就提出解决方案。

出现上述任何一种情况，都意味着：停止。返回阶段 1。 如果修复失败 3 次以上，应重新审视架构。

快速参考

阶段	主要活动	成功标准
1. 根本原因	阅读错误、复现问题、检查变更、收集证据	理解问题是什么以及为什么发生
2. 模式	查找可正常工作的示例并进行比较	找出差异
3. 假设	提出理论并进行最小化测试	得到确认或提出新假设
4. 实施	创建测试、修复并验证	Bug 已解决，测试通过

未找到根本原因时

如果问题确实取决于环境、时序或外部因素：记录调查内容，实施适当的处理方式（重试、超时、错误消息），并添加监控。但 95% 的“未找到根本原因”情况，都是调查不充分所致。

异常处理

• 解析失败：报告原始输出并请求澄清——不要猜测
• 文件缺失：立即升级处理——这不属于常规调试场景
• 用户中断：恢复时重新阅读调查报告，并从最后完成的阶段继续