diagnose-bug

诊断 Bug

不要从症状直接跳到修复。先确认实际发生了什么、这是否真的是缺陷，以及原因是什么。

关卡

以下四项是这项技能的核心；下面的流程旨在满足这些要求。

1. 先复现，再编辑。 通过可重复的信号观察到症状之前，不得修改产品。如果无法复现，请说明尝试了什么以及还需要什么信息——不要凭猜测修复。
2. 先提出假设，再做更改。 将每个候选原因表述为可证伪的预测，并在编写任何修复前进行测试。
3. 用相同信号验证。 重新运行复现步骤，并确认症状已消失，从而确认修复有效。应用 /verification-evidence。
4. 专注于当前 Bug。 过程中发现的其他问题应报告，不要在同一次更改中修复。

流程

1. 重述症状

用具体信息记录报告：发生了什么、预期是什么、发生在哪里，以及已知的输入、环境、时间或近期更改。区分观察到的事实和猜测。即使只粘贴了错误或日志、没有附带请求，也仍然是报告；请重述其中显示的内容。

2. 分类：缺陷、设计还是环境

在查找原因之前，先确认预期本身是否合理。报告中的行为可能正是系统按设计运行的结果。

• 设计 — 代码、文档、配置或先前接受的计划有意实现了此行为（例如阻止未认证访问的身份验证门槛、速率限制，或拒绝下载受限模型）。请引用说明此意图的依据。
• 环境或配置 — 系统本身正常，但用户的设置、凭据、部署目标或数据有问题（例如缺少环境变量、本地数据库与远程数据库不一致，或构建过期）。
• 缺陷 — 行为与预期设计相矛盾。
• 未知 — 无法从代码库中确定设计意图。

对于设计或环境问题，到此为止，并说明原因、证据，以及用户应如何更改：调整自己的设置，或者，如果希望改变设计本身，则通过 /plan-it 提交功能请求。不要“修复”有意为之的行为。如果意图未知，应结合证据向用户提问，而不是自行决定。

3. 建立反馈循环

找到能可靠地显示用户确切症状的最快信号，而不只是查看附近代码。如果症状出现在代码库的验证技能所覆盖的界面上，请运行其 Doctor，并通过 Launch 和 Drive 步骤复现症状。选择合适的方式；以下是可选方案，并非必须依次执行：

1. 现有失败测试，或针对性的新回归测试。
2. 精简的命令、脚本或 CLI 调用。
3. 针对运行中系统的 HTTP 请求、UI 交互或浏览器自动化。
4. 重放真实输入、日志、跟踪记录、负载或快照。
5. 围绕相关模块搭建一次性测试工具。
6. 对间歇性症状使用重复输入或生成的输入。
7. 暂时无法自动化时，使用手动复现步骤。

创建测试或测试工具属于文件更改；只有请求方授权编辑时才能进行。读取、运行和查询无需此类授权，但写入共享系统或生产系统始终需要批准，即使只是为了复现问题也一样。

4. 复现并缩小范围

运行反馈循环并确认症状。然后缩减场景，直到剩余的输入、配置和步骤都不可或缺。如果无法复现，可能是环境问题或问题已修复——请说明证据指向哪种情况。

5. 追踪并提出假设

沿相关入口、状态变化、IO 和错误路径追踪行为。为可能的原因排序，并分别表述为：

If <cause> is true, then <probe or change> should show <result>.

先测试可能性最高的原因，每次只改变一个变量。当用户询问先前的诊断是否有误时，应将该诊断视为假设并重新测试，而不是为其辩护。

6. 修复并验证

如果用户要求修复，且已确认原因，请进行能消除问题的最小改动，然后重新运行步骤 3 中的信号，并证明该症状已消失。如果回归测试能够捕获原因，请保留该测试。如果仓库有验证技能，请在同一差异中更新所有 Where it lives 路径涉及修复的功能文件，以及诊断过程中发现的任何启动步骤或注意事项。如果修复需要做出设计决策，或超出此问题的范围，请停止并转交给 /plan-it。

输出

- Symptom: <restated>
- Classification: <defect / design / environment / unknown> — <evidence>
- Reproduction: <signal and result, or what blocked it>
- Cause: <confirmed hypothesis and the evidence>
- Fix: <change made, or "diagnosis only">
- Verification: <same signal rerun, its evidence kind, runs and results, uncovered conditions — or "unverified" with why it could not be rerun or did not settle>
- Other issues found: <reported, not fixed>
- Verify skill: <what this diagnosis had to discover about running the project, and — if a fix was made — the feature-file updates in the fix's diff; or "nothing new">

完成标准

报告应基于证据对行为进行分类。对于设计或环境问题，应说明原因和后续步骤，且未更改产品代码。对于缺陷：已复现该症状（或说明了阻碍因素），原因是经过测试的假设；如果用户要求修复，则修复后重新运行了相同的复现步骤，且不再出现该症状，按步骤 6 的要求更新了验证技能，并报告了其他问题但未修复。