diagnosing-bugs

诊断错误

在修复之前，先查明已观察到的故障机制。本技能负责诊断，不负责生产环境修复。

从简单入手。阅读错误信息、堆栈、现有复现或捕获的工件，以及近期相关变更。如果这些证据已能区分故障机制，就直接报告，不要为了流程更长而人为增加步骤。只有在不确定性需要时才深入调查。

界定症状

记录确切的已观察症状、受影响的用户或系统路径、修订版本和环境、已知触发条件、是否具有确定性或已观察到的故障率，以及重要约束。区分实际观察到的内容与他人报告或推断的内容。

不要在命令、笔记和返回的证据中包含秘密、私密数据、凭据或无关负载。只有在获得授权时才在本地保留原始工件；仅公开支持结论所需的最少脱敏证据。

建立诊断信号

选择现有证据路径中最窄且忠实的一种：

• 在与故障相同的重要界面上执行复现；
• 通过日志、跟踪记录、性能分析、调试器或临时插桩观察实时运行情况；或
• 使用已有的固定工件，例如跟踪记录、性能分析结果、核心转储、HAR 或结构化日志，并确认其来源和修订版本。

如果能够在保留症状语义的前提下实现，就优先采用精确、可重复且速度合理的红灯复现。对于间歇性故障，应测量其基线发生率，并在不改变故障含义的情况下提升可观测性或增加重复次数。不要为了声称实现了复现循环而构建低保真模拟。

对于固定工件，应缩小相关时间段或路径，将观察结果对应到匹配的源代码和修订版本，并且仅在对比工件有助于区分重要的替代解释时才寻找它。可信的工件无需实时重现故障，也能查明故障机制。

只有在必须区分成因时，才允许使用临时本地插桩或一次性测试框架。为其添加唯一标识；未经明确授权，不要对在线系统进行可能造成重大后果的更改；返回前将其移除。

如果无法获得忠实的信号，应以 Inconclusive 记录结论，并指出具体缺少的工件、访问权限、环境、授权或观察能力。

区分故障机制

只有在缩小假设范围时才进行最小化：每次移除一个输入、依赖、时序条件、进程边界或状态维度，同时保留症状。当进一步精简会降低保真度或不再影响判断时，就应停止。

仅提出当前证据支持的假设。对于每种可能的成因，都要说明哪种观察结果可以将其与重要的替代解释区分开，然后每次运行一个探查或改变一个变量。根据故障类型，可采用的探查包括正常与故障情况对比、历史记录或二分查找、边界插桩、依赖替换、并发控制，以及跟踪记录或性能分析结果对比。

当假设确实相互独立且不会争用可变状态时，可选用只读并行调查人员。必须由一位负责人根据实际证据核实并协调其结论。默认不要分派多个调查任务。

只有当证据能将提出的故障机制与重要的替代解释区分开时，才可认定为 Diagnosed。看似合理的说法、相关性、症状消失或重启成功，都不能算作根因。

总结并清理

移除带有唯一标记的插桩和一次性诊断产物，恢复调查所涉及的所有状态，并仅保留已接受的源产物和经过脱敏的证据。在使用此技能期间，不要提交更改、创建 ADR 或计划、分派工作，也不要通过编辑生产代码来修复问题。

确定且仅确定一个诊断结果：

• Diagnosed：说明症状、证据、根因和区分性观察。包括修订版本和环境、精确的复现步骤及结果、确定性或测得的发生率、最小且忠实的场景或产物、已测试或已排除的假设、证据局限，以及仅在有实质意义时提供忠实的回归测试接入点。
• Inconclusive：说明症状、现有证据、确切阻碍因素和范围最小的后续操作。包括修订版本和环境、尝试及结果、已排除的假设；仅在有实质意义时说明剩余可能性；将每个剩余可能性标记为假设，并注明 Root cause: not established.

如果任务仅限于诊断，则返回诊断结果。如果已获准修复，则在编辑前记录诊断结果，并根据调用方的实现约定，由同一执行者继续完成修复，并将其纳入本次交付的最终说明。使用 strategic-programming 进行修复；仅当复现过程对应忠实且受维护的接入点时，才将其转化为回归测试，并在该阶段运行适用的项目检查。

完成标准

通过区分性证据确定故障机制，或以准确的解除阻碍条件如实结束调查。将观察与推断分开，不暴露敏感数据，移除临时更改，并确保没有把诊断误当作修复。