diagnose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

diagnose — Root-Cause Isolation

diagnose — 根因隔离

Operating Invariants

操作不变量

Investigation Boundary: Read production source and existing tests; write temporary harnesses, fixtures, trace replays, and report files only inside
```
.agents/scratch/
```
. End at a root-cause report; leave production fixes, permanent tests, and fix changesets to subsequent work.
Working Tree Preservation: Preserve pre-existing changes and scratch artifacts. Run probes against isolated copies or existing read-only seams; keep instrumentation out of production source. Tag temporary probes
```
[DEBUG-<hex>]
```
and remove only session-owned instrumentation after collecting evidence.
Sensitive Evidence & Environment: Redact secrets before logging; never inspect secret files (
```
.env*
```
,
```
*.key
```
,
```
*.pem
```
). Ground runners in
```
.agents/environment.md
```
(fallback to
```
.agents/dev-environment.md
```
if present); confine execution strictly to local scratch boundaries without touching production or host-level containers.

调查边界：阅读生产源代码和现有测试；临时 harness、fixture、trace replay 和报告文件只能写入
```
.agents/scratch/
```
。以根因报告为终点；生产修复、永久测试和修复 changeset 留给后续工作。
工作树保留：保留预先存在的更改和 scratch 制品。在隔离副本或现有只读 seam 上运行探针；不要在生产源代码中加入 instrumentation。将临时探针标记为
```
[DEBUG-<hex>]
```
，收集证据后仅移除本会话创建的 instrumentation。
敏感证据与环境：记录日志前对 secret 进行脱敏；绝不检查 secret 文件（
```
.env*
```
、
```
*.key
```
、
```
*.pem
```
）。以
```
.agents/environment.md
```
作为执行依据（如果存在
```
.agents/dev-environment.md
```
，则回退使用后者）；严格将执行限制在本地 scratch 边界内，不触碰生产环境或宿主机级容器。

Domain Rubric

领域准则

Intake and Causal Evidence

接收与因果证据

Accept a defect description, error, log, stack trace, or reproduction. Identify expected behavior, observed behavior, relevant environment, and the execution seam; distinguish missing evidence from contradicted evidence.
Begin investigation with available evidence even when an executable RED is unavailable. Treat a failing assertion as symptom evidence; establish cause through a discriminating probe, a conclusive execution trace, or a verified causal chain.
Separate trigger and context from the mechanism that produces the failure. For each defensible hypothesis, state a prediction:
```
If <cause>, then <controlled probe> changes <observation>.
```
Test competing explanations when evidence permits; vary one causal factor at a time and record results that support or falsify each candidate. Prefer direct traces for obvious syntax errors or deterministic failures over unnecessary harnesses.

接受缺陷描述、错误、日志、stack trace 或复现。确定预期行为、观察到的行为、相关环境和执行 seam；区分证据缺失与证据矛盾。
即使没有可执行的 RED，也应从现有证据开始调查。将失败断言视为症状证据；通过有区分度的探针、决定性的执行 trace 或经验证的因果链确立原因。
将触发因素和上下文与产生失败的机制区分开来。对于每个有依据的假设，陈述一个预测：
```
If <cause>, then <controlled probe> changes <observation>.
```
在证据允许时检验竞争性解释；每次只改变一个因果因素，并记录支持或证伪各候选原因的结果。对于明显的语法错误或确定性失败，优先使用直接 trace，而不是不必要的 harness。

Reproduction and Feedback Loops

复现与反馈循环

Choose the tightest loop faithful to the symptom and available runtime:

Seam	Investigation method
Existing test	Run the focused assertion at the failing call site
Running process	Invoke the CLI or HTTP path and compare expected/actual output
Isolated callable	Build a minimal scratch harness; disclose substituted I/O
Captured event	Replay sanitized payloads, logs, or HAR data in scratch
Historical regression	Compare revisions in an isolated scratch checkout
Interactive-only trigger	Adapt the local loop template in scratch; capture redacted responses

Minimize inputs, configuration, and steps while preserving the exact symptom; retain every factor needed for fidelity, including relevant integration behavior.
For intermittent failures, control seeds, clocks, event ordering, or concurrency where feasible. Report attempts, failures, and intervention results; use bounded repetitions rather than treating one lucky pass as proof.
Preserve real architectural seams. If mocks omit the suspected mechanism or no faithful seam is available, document that proof gap and continue evidence-based investigation within scope.

选择最紧凑且忠实于症状和可用 runtime 的循环：

Seam	调查方法
现有测试	在失败调用点运行聚焦断言
运行中的进程	调用 CLI 或 HTTP 路径，并比较预期输出与实际输出
隔离的可调用单元	构建最小 scratch harness；说明替换的 I/O
捕获的事件	在 scratch 中重放已脱敏的 payload、日志或 HAR 数据
历史回归	在隔离的 scratch checkout 中比较各修订版本
仅交互式触发	在 scratch 中调整本地循环模板；捕获已脱敏的响应

在保持症状完全一致的同时，最大限度减少输入、配置和步骤；保留保真度所需的每个因素，包括相关的集成行为。
对间歇性失败，在可行情况下控制 seed、时钟、事件顺序或并发。报告尝试、失败和干预结果；使用有限次数的重复，而不是将一次侥幸通过视为证据。
保留真实架构 seam。如果 mock 省略了疑似机制，或没有忠实的 seam 可用，应记录证明缺口，并在范围内继续基于证据的调查。

Conclusion States

结论状态

```
CONFIRMED
```
: Evidence verifies the causal mechanism, including the link from that mechanism to the reported symptom.
```
INFERRED
```
: Evidence supports a specific causal hypothesis, but a stated gap prevents confirmation.
```
REJECTED
```
: Discriminating evidence falsifies the investigated causal claim in the stated scope; identify the claim rather than implying the defect is disproven.
```
UNRESOLVED
```
: Available evidence supports no defensible cause, or an input, environment, or access blocker prevents a meaningful conclusion.

```
CONFIRMED
```
：证据验证了因果机制，包括该机制与所报告症状之间的联系。
```
INFERRED
```
：证据支持某个具体因果假设，但存在明确的证据缺口，无法确认。
```
REJECTED
```
：有区分度的证据在既定范围内证伪了所调查的因果主张；应明确指出被否定的具体主张，而非暗示缺陷本身不成立。
```
UNRESOLVED
```
：现有证据无法支持任何有依据的原因，或输入、环境或访问权限问题阻碍了得出有意义的结论。

Canonical Output Contract

标准输出约定

Produce one compact report. Include commands, relevant observations, and source locations sufficient to reproduce or inspect the reasoning; keep raw logs in sanitized scratch artifacts when needed.

markdown

undefined

生成一份紧凑报告。包含命令、相关观察结果和源文件位置，足以复现或检查推理过程；必要时将原始日志保存在已脱敏的 scratch 制品中。

markdown

undefined

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)

undefined

undefined

Routing

路由

An existing candidate and direction need solution proof → (via /spike).
Root-cause findings need a solution direction → (via /architect-decision).
Environment defects or missing runtime dependencies prevent reproduction → (via /env-doctor).

现有候选方案与解决方向需要经过方案验证 →（通过 /spike）。
根因发现需要确定解决方向 →（通过 /architect-decision）。
环境缺陷或缺失 runtime 依赖导致无法复现 →（通过 /env-doctor）。

Execution Protocol

执行协议

Ground the symptom in supplied evidence and inspect the relevant call chain. Record the narrow causal question and available verification seam.
Establish and minimize a faithful RED loop when possible. When execution is unavailable, continue through traces and source evidence while recording the missing proof.
Probe ranked hypotheses until a cause is confirmed, supported with an explicit gap, falsified, or unresolved. Stop an investigation branch when further probes require unavailable input/access or merely repeat the same signal.
Present the root-cause report with its state and proof limits. Preserve useful sanitized reproduction artifacts, remove session-owned instrumentation, and verify production files remain unchanged.

以提供的证据为基础确定症状，并检查相关调用链。记录范围明确的因果问题和可用的验证 seam。
尽可能建立并最小化忠实的 RED 循环。无法执行时，继续通过 trace 和源代码证据推进，同时记录缺失的证明。
依次探测按优先级排序的假设，直至原因得到确认、在明确说明证据缺口的前提下得到支持、被证伪或保持未解决状态。如果进一步探测需要不可获得的输入或访问权限，或者只是重复相同信号，则停止该调查分支。
出具根因报告，注明其状态和证明边界。保留有用的已脱敏复现制品，移除本会话创建的 instrumentation，并确认生产文件保持不变。