diagnose

diagnose — 根因隔离

操作约束

• 调查边界：阅读生产源代码和现有测试；仅在 .agents/scratch/ 内编写临时测试框架、测试夹具、跟踪重放和报告文件。调查以根因报告结束；将生产修复、永久测试和修复变更集留给后续工作。
• 工作树保护：保留已有更改和临时文件。通过隔离副本或现有只读接口执行探查；不要在生产源代码中加入检测代码。为临时探查标记 [DEBUG-<hex>]，收集证据后仅移除本次会话添加的检测代码。
• 敏感证据与环境：记录日志前先删除机密信息；绝不检查机密文件（.env*、*.key、*.pem）。以 .agents/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>

路由

• 在既有架构中找到根因后，需要符合生态规范的设计 →（通过 /conform-design）。
• 已有候选方案和方向，需要验证解决方案 →（通过 /spike）。
• 找到根因后，需要确定宏观架构方向或权衡取舍 →（通过 /architect-decision）。
• 环境缺陷或运行时依赖缺失导致无法复现 →（通过 /env-doctor）。

执行协议

1. 根据提供的证据定位症状，并检查相关调用链。记录范围明确的因果问题，以及可用的验证切入点。
2. 尽可能建立并精简可靠的 RED 循环。如果无法执行，则根据跟踪信息和源代码证据继续调查，同时记录缺失的证明。
3. 依次验证排序后的假设，直到确认原因、明确证据缺口、证伪或仍未解决。如果进一步探查需要无法获取的输入或访问权限，或只会重复相同信号，则停止该调查分支。
4. 提交根因报告，说明当前状态及证明的局限。保留有用且已清理敏感信息的复现产物，移除会话专属的插桩，并验证生产文件未被更改。