investigate

核心规则

不理解根本原因，就不要修复。 使用经过验证的证据解释原因如何导致症状。即使某个原因看起来显而易见，也仍需验证；已经确认的原因无需重新提出假设。

第 1 步 — 了解症状

从报告、可用日志、项目配置和先前尝试中收集以下信息。仅在缺失的信息会实质影响调查时才询问：

• 确切症状： 原样记录的错误、错误输出、崩溃或无声失败。
• 复现方式： 可靠的触发条件、发生频率，以及间歇性失败的条件。
• 起始时间： 问题何时开始，以及可能相关的变更。
• 环境： 问题出现的位置，以及与正常环境的相关差异。
• 先前尝试： 测试或更改过什么，以及观察到的结果。

第 2 步 — 提出假设

根据现有证据提出合理的原因。按证据支持程度排序，并说明不确定性；不要编造百分比，也不要为了凑固定数量而填充列表。针对每个假设，指出一项可用于区分原因的检查：

Hypothesis: [possible cause]
Evidence: [observations supporting it]
Would rule it out: [contradicting observation]
Next check: [how to obtain evidence that distinguishes it from alternatives]

常见类别：

• 数据假设错误：值缺失、类型或形状异常。
• 状态或时序：并发、缓存过期或操作顺序。
• 配置或环境差异。
• 外部依赖项或库的行为发生变化。
• 相关源代码变更引发的回归。

用户认为某个领域不可能出错，这会影响调查优先级，但本身并不能排除该领域。

第 3 步 — 以最小干扰测试假设

优先使用现有日志、调试器、配置检查和受控复现。根据检查区分原因的能力、成本和运行影响来选择检查。

当观察不足时，在授权范围内进行可逆的诊断性更改。记录所做的更改，保留现有工作，并在检查后移除临时检测代码，或还原仅用于诊断的依赖项更改。只有当诊断性更改是约定修复的一部分时，才予以保留。

假设	示例检查
某个值缺失	在相关边界处使用调试器或临时的定向日志检查该值
操作发生竞争	在受控复现中比较操作时序和状态转换
配置存在差异	仅比较相关设置；对机密信息进行脱敏，并优先检查敏感值是否存在或是否相等
依赖项行为发生变化	在隔离的复现环境中比较相关版本，不要更改共享环境

检查源代码历史，查找与受影响行为及症状起始时间相关的变更。根据相关证据进行追溯，不要固定检查提交数量或天数。记录每项检查的结果，并修订或排除假设。

第 4 步 — 追踪数据流

利用证据追踪受影响的路径，并在过程中检验假设：

[Request/Event enters at: ]
  → [Layer 1] — state here: [what you found]
  → [Layer 2] — state here: [what you found]
  → [Where behavior diverges from expected] — state here: [what you found]
  → [Where the symptom manifests]

找出实际行为首次经验证偏离预期的位置。在适用时注明确切的文件和行号，解释它如何导致症状，并继续向上游追踪，直到排除更早的原因。随着新证据出现，第 2 至第 4 步可以相互补充。

第 5 步 — 修复已确认的原因

做出能够解决已验证根本原因的最小改动。编辑前，说明原因以及拟议的改动为何能解决问题。仅在相关未解决问题会影响用户结果或本次修复范围时，才提及这些问题。

根据项目规则和风险决定编写测试的顺序。添加回归测试，在触发条件下重现原始故障，在修复前版本上失败，并在应用修复后通过。断言相关的可观察行为，而不是私有实现细节。如果问题无法稳定复现，或所需环境不可用，应说明证据的局限和仍待验证的事项，不要声称修复已得到证实。

遵循用户或项目的提交安排；否则，将修复和回归测试分别提交，并且只暂存各自预期的改动。编写测试的顺序与提交顺序是两个不同的决定：可以先编写测试，即使将测试与修复分开提交，且在修复之后提交。

第 6 步 — 验证

应用修复后，重新执行原始复现步骤，并验证回归测试在修复前后的表现。针对受影响的行为运行相关检查，并遵循项目的完整测试套件规则。确认临时诊断改动已清理，或有意保留。

如果症状仍然存在，请根据观察到的结果重新审视假设和数据流。再次尝试修复前，先说明哪些新证据为这次尝试提供了依据。如果继续尝试只会重复缺乏依据的猜测，请遵循下方的停止条件。

第 7 步 — 当证据无法推进时停止或请求帮助

如果下一次尝试没有新证据或不同的诊断检查、会重复已被证伪的猜测，或需要不可用的信息、访问权限、专业知识或授权，请暂停受影响的修复尝试。继续进行能够安全地产生新证据的独立调查。无论之前失败了多少次，只要后续步骤有证据支持，就可以继续。

报告实际阻碍和具体的下一步：

Blocked investigation: [what cannot currently be established]

Attempts and observations:
- [check or fix attempted, what changed, and observed result]

Current understanding:
[confirmed facts, remaining hypotheses, and what is uncertain]

Missing evidence or access:
[what is needed to distinguish the remaining causes]

Recommended next step:
[specific check, information request, or authorized action]