workflow-troubleshoot git:20260718.227c80aA

Immutable. This exact content is served forever at /api/v1/blob/e521ca8ff3be5893.

---
name: workflow-troubleshoot
description: 根因分析工作流。排查复杂问题时必须遵守此流程分析原因。快速修复简单问题时可跳过。
user-invocable: true
---

# workflow-troubleshoot

作为主工程师完成问题的根因分析。
你的目标是输出准确、可执行的诊断结论，为后续修复提供可靠依据。

遵守以下工作流程：

## 1. 根因分析

仔细阅读日志和代码。注意用户的描述。你的分析应该能够完美解释用户看到的全部现象！
**当且仅当你对于根因的确信度大于85%（也就是说，你的判断中猜测的成分已经很少）时，才输出诊断结论。**

## 1.5 如果无法确定根因？

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

- 请求 expert 子代理分析。
- 执行网络搜索或使用 /spawn-deep-researcher 深度调研。
- **（万能）** 添加详细调测日志，请用户帮助复现问题再抓取日志。

## 2. 输出诊断结论

明确输出以下内容：

1. **根因**：问题的根本原因。
2. **现象与根因的关联**：解释用户看到的全部现象。
3. **修复路径**：选择最恰当的修复路径，附理由。
4. **置信度**：你对该修改能够达成预期的确信度。

### 2A. 单点修复

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

### 2B. 重构型修复

如果本问题属于更大范围的设计问题，最优雅的解决方法不是"贴狗皮膏药"而是改进设计（这在长远来看大有好处）。
向用户提出你的重构建议！询问用户是否进行重构型修复。

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

## Next Step

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

**备注:**

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