git:20260818.096d121 to git:20260919.8080466

---

name: workflow-troubleshoot

description: 根因分析工作流。排查复杂问题时必须遵守此流程分析原因。

user-invocable: true

---

# workflow-troubleshoot

作为主工程师完成问题的根因分析。

你的目标是输出准确、可执行的诊断结论，为后续修复提供可靠依据。

遵守以下工作流程：

仔细阅读用户的描述。通过构造测试用例 / e2e 测试完整复现问题场景。

不通过的测试用例在本问题解决时应该通过，作为回归测试的验收标准。

若当前问题很难模拟构造或无法复现，可以添加调测日志，并请求用户实机复现，确保通过日志准确捕捉问题。

**当且仅当你能通过测试用例或实机日志完整复现问题，并确定回归的验收标准时，进入下一步。**

> 特例1：对于范围小、原因极明确的问题，可以跳过本步骤。

> 特例2：若问题属于难以测量的体验问题，在得到用户同意后可以跳过本步骤

仔细阅读日志和代码。你的分析应该能够完美解释用户看到的全部现象！

**当且仅当你对于根因的确信度大于85%（也就是说，你的判断中猜测的成分已经很少）时，才输出诊断结论。**

如果感到问题较难分析，不要假装你已经明白了原因然后盲目修复！那只会让问题扩大！

你可以用以下方式辅助分析：

- 请求 expert 子代理分析。

- 执行网络搜索或使用 /spawn-deep-researcher 深度调研。

- **（万能）** 添加详细调测日志，请用户帮助复现问题再抓取日志。

明确输出以下内容：

1. **根因**：问题的根本原因。

2. **现象与根因的关联**：解释用户看到的全部现象。

3. **修复路径**：选择最恰当的修复路径，附理由。

4. **置信度**：你对该修改能够达成预期的确信度。

5. **验收标准**

如果问题为单点问题，建议精准修复路径。

如果本问题属于更大范围的设计问题，最优雅的解决方法不是"贴狗皮膏药"而是改进设计（这在长远来看大有好处）。

向用户提出你的重构建议！询问用户是否进行重构型修复。

诊断结论及修复方向输出到 `/docs/issues/yymmdd-{issue_name}/yymmdd-{issue_name}.troubleshoot.md`。

## Next Step

用户书面确认诊断结果后，请读取 /workflow-implement-review 进入修复实施阶段。

**备注:**

如果你连续多次分析都未能达成确信，意味着当前思路不可靠或缺乏关键线索，继续试错只会引入更多不确定性。请清空既有思路从零梳理，并更积极地采用 1.5 所述方法。真正的原因常常比预想的简单！