diagnose

diagnose — 根因隔离

操作不变量

• 调查边界：阅读生产源码和现有测试；仅在 .agents/scratch/ 中编写临时测试框架、夹具、跟踪回放和报告文件。以根因报告结束；将生产修复、永久测试和修复变更集留给后续工作。
• 工作树保护：保留现有更改和临时文件。使用隔离副本或现有只读接口运行探测；不要在生产源码中加入检测代码。为临时探测标记 [DEBUG-<hex>]，收集完证据后只移除本次会话添加的检测代码。
• 敏感证据与环境：记录日志前先编辑掉机密；绝不检查机密文件（.env*、*.key、*.pem）。根据 .agents/dev-environment.md 配置运行器；严格将执行限制在本地临时目录范围内，不得触及生产环境或主机级容器。

领域准则

输入与因果证据

• 接受缺陷描述、错误、日志、堆栈跟踪或复现步骤。识别预期行为、实际行为、相关环境和执行接口；区分证据缺失与证据矛盾。
• 即使无法执行 RED，也要依据现有证据开始调查。将断言失败视为症状证据；通过具有区分力的探测、确凿的执行跟踪或已验证的因果链确定原因。
• 将触发条件和上下文与导致故障的机制区分开。针对每个有依据的假设，说明预测：If <cause>, then <controlled probe> changes <observation>.
• 证据允许时，测试相互竞争的解释；每次只改变一个因果因素，并记录支持或证伪各候选解释的结果。对于明显的语法错误或确定性故障，优先使用直接跟踪，而非不必要的测试框架。

复现与反馈循环

选择最贴合症状和可用运行时的最精简循环：

接口	调查方法
现有测试	在失败的调用点运行针对性断言
运行中的进程	调用 CLI 或 HTTP 路径，并比较预期与实际输出
隔离的可调用对象	构建最小临时测试框架；说明替代的 I/O
捕获的事件	在临时目录中回放经过脱敏的负载、日志或 HAR 数据
历史回归	在隔离的临时检出目录中比较修订版本
仅交互触发	在临时目录中改用本地循环模板；捕获经过脱敏的响应

• 在保留确切症状的前提下，尽量减少输入、配置和步骤；保留确保忠实复现所需的所有因素，包括相关的集成行为。
• 对于间歇性故障，在可行时控制随机种子、时钟、事件顺序或并发。报告尝试次数、失败情况和干预结果；采用有界重复测试，不要将一次侥幸通过当作证据。
• 保留真实的架构接口。如果模拟对象遗漏了疑似机制，或没有忠实的接口可用，应记录这一证据缺口，并在范围内继续基于证据调查。

结论状态

• CONFIRMED：证据验证了因果机制，包括该机制与报告症状之间的联系。
• INFERRED：证据支持某个具体的因果假设，但存在明确缺口，无法确认。
• REJECTED：具有区分力的证据在所述范围内证伪了所调查的因果主张；指出具体主张，不要暗示缺陷已被证伪。
• UNRESOLVED：现有证据无法支持任何有依据的原因，或输入、环境或访问限制妨碍了有意义的结论。

规范输出约定

生成一份精简报告。提供足以复现或检查推理过程的命令、相关观察结果和源码位置；必要时，将原始日志保存在经过脱敏的临时文件中。

# Root-Cause Report: <defect>

State: <CONFIRMED | INFERRED | REJECTED | UNRESOLVED>
Conclusion: <causal mechanism, supported hypothesis, rejected claim, or unresolved question>
Scope: <symptom, runtime/environment, and inspected seam>
Evidence: <commands or trace references; observed results; discriminating causal link>
Conditions and proof limits: <assumptions, substitutions, missing evidence, and applicability limits>

## Competing explanations *(omit if none were investigated)*
<claim -> probe/prediction -> observation -> supported or falsified>

## Reproduction *(omit if no executable or interactive loop was established)*
<scratch path or existing command; required setup; assertion and observed symptom>

路由

• 已有候选方案和方向需要验证其可行性 →（通过 /spike）。
• 根因调查结果需要一个解决方向 →（通过 /architect-decision）。

执行协议

1. 根据提供的证据梳理症状，并检查相关调用链。记录具体的因果问题和可用的验证切入点。
2. 尽可能建立并缩小一个忠实的 RED 循环。如果无法执行，则根据跟踪记录和源代码证据继续调查，并记录缺失的验证依据。
3. 按优先级探查假设，直到原因得到确认、发现明确的证据缺口、被证伪或仍无法确定。如果后续探查需要无法获取的输入或访问权限，或者只会重复相同信号，则停止该调查分支。
4. 提交根因报告，说明其状态和证据限制。保留有用且已脱敏的复现材料，移除由当前会话添加的检测代码，并确认生产文件未发生变更。