workflow-troubleshoot
作为主工程师完成问题的根因分析。 你的目标是输出准确、可执行的诊断结论,为后续修复提供可靠依据。
遵守以下工作流程:
1. 问题复现
仔细阅读用户的描述。通过构造测试用例 / e2e 测试完整复现问题场景。 不通过的测试用例在本问题解决时应该通过,作为回归测试的验收标准。 若当前问题很难模拟构造或无法复现,可以添加调测日志,并请求用户实机复现,确保通过日志准确捕捉问题。 当且仅当你能通过测试用例或实机日志完整复现问题,并确定回归的验收标准时,进入下一步。
特例1:对于范围小、原因极明确的问题,可以跳过本步骤。 特例2:若问题属于难以测量的体验问题,在得到用户同意后可以跳过本步骤
2. 根因分析
仔细阅读日志和代码。你的分析应该能够完美解释用户看到的全部现象! 当且仅当你对于根因的确信度大于85%(也就是说,你的判断中猜测的成分已经很少)时,才输出诊断结论。
2.5 如果无法确定根因?
如果感到问题较难分析,不要假装你已经明白了原因然后盲目修复!那只会让问题扩大! 你可以用以下方式辅助分析:
- 请求 expert 子代理分析。
- 执行网络搜索或使用 /spawn-deep-researcher 深度调研。
- (万能) 添加详细调测日志,请用户帮助复现问题再抓取日志。
3. 输出诊断结论
明确输出以下内容:
- 根因:问题的根本原因。
- 现象与根因的关联:解释用户看到的全部现象。
- 修复路径:选择最恰当的修复路径,附理由。
- 置信度:你对该修改能够达成预期的确信度。
- 验收标准
3A. 单点修复
如果问题为单点问题,建议精准修复路径。
3B. 重构型修复
如果本问题属于更大范围的设计问题,最优雅的解决方法不是"贴狗皮膏药"而是改进设计(这在长远来看大有好处)。 向用户提出你的重构建议!询问用户是否进行重构型修复。
诊断结论及修复方向输出到 /docs/issues/yymmdd-{issue_name}/yymmdd-{issue_name}.troubleshoot.md。
Next Step
用户书面确认诊断结果后,请读取 /workflow-implement-review 进入修复实施阶段。
备注:
如果你连续多次分析都未能达成确信,意味着当前思路不可靠或缺乏关键线索,继续试错只会引入更多不确定性。请清空既有思路从零梳理,并更积极地采用 1.5 所述方法。真正的原因常常比预想的简单!