# Workflow Troubleshoot

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

- Skill: `john-walks-slow/workflow-troubleshoot` (Agent Skill)
- Install (CLI): `npx skillmds@latest add john-walks-slow/workflow-troubleshoot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/john-walks-slow/workflow-troubleshoot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: john-walks-slow (https://skillmd.com/u/john-walks-slow)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/john-walks-slow/workflow-troubleshoot

---


# workflow-troubleshoot

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

遵守以下工作流程：

## 1. 问题复现

仔细阅读用户的描述。通过构造测试用例 / e2e 测试完整复现问题场景。
不通过的测试用例在本问题解决时应该通过，作为回归测试的验收标准。
若当前问题很难模拟构造或无法复现，可以添加调测日志，并请求用户实机复现，确保通过日志准确捕捉问题。
**当且仅当你能通过测试用例或实机日志完整复现问题，并确定回归的验收标准时，进入下一步。**

> 特例1：对于范围小、原因极明确的问题，可以跳过本步骤。
> 特例2：若问题属于难以测量的体验问题，在得到用户同意后可以跳过本步骤

## 2. 根因分析

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

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

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

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

## 3. 输出诊断结论

明确输出以下内容：

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

### 3A. 单点修复

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

### 3B. 重构型修复

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

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

## Next Step

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

**备注:**

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