Back to Details

diagnose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diagnose

诊断

Use when correctness is uncertain. Do not patch from vibes: make the bug observable, prove the cause, fix the smallest thing, verify against the original symptom. Use the target repo's native build/test/runtime commands as the evidence loop.
当正确性无法确定时使用。不要凭感觉打补丁：让 bug 可观测，证明原因，只修复最小范围，并针对原始症状进行验证。使用目标 repo 原生的 build/test/runtime 命令作为证据闭环。

1. Define the symptom

1. 定义症状

text
Expected: ...
Actual: ...
Observed in: command/log/file/process id/agent id/artifact id
If the report is vague, ask for the missing observable (exact command, stack trace, id, log path, repro steps). Do not chase unrelated warnings until they connect to this symptom.
text
预期：...
实际：...
观测位置：command/log/file/process id/agent id/artifact id
如果问题描述含糊，请询问缺失的可观测信息（准确命令、stack trace、id、日志路径、复现步骤）。在警告与当前症状建立关联之前，不要追查无关警告。

2. Orient just enough

2. 只做必要的方向定位

Identify only the smallest relevant area: repo root/cwd, package/crate/service, entrypoint triggering the symptom, closest test/fixture/log source, and expensive commands to avoid. Never map the whole codebase.
仅确定最小相关范围：repo 根目录/cwd、package/crate/service、触发症状的 entrypoint、最接近的 test/fixture/log 来源，以及需要避免执行的耗时命令。绝不要梳理整个代码库。

3. Build the feedback loop

3. 建立反馈闭环

Find the fastest deterministic loop that reaches the bug, e.g. 
cargo test -p <crate> <filter> -- --nocapture
, a focused unit test, a CLI run on fixture input, a request script against a dev server, a replay of a captured event, or a small throwaway harness when no seam exists.
  • Slow repro loops and servers: run them in hc (
    hc run --bg
    , then 
    hc wait
    or 
    hc wait --output <ready line>
    ; see the 
    hc
    skill) — never 
    &
    , 
    nohup
    , 
    disown
    , 
    setsid
    .
  • Subagents only for independent investigation, tightly scoped with 
    cwd
    and exact files; continue other runnable probes while it runs; its report arrives by itself.
  • For long diagnoses, save a chain link (
    chains
    skill) with the symptom, repro command, hypotheses tested, files touched, ids, and next step.
Do not proceed until the loop reproduces the bug or proves more evidence is needed.
找到能够触达 bug 的最快、确定性最高的闭环，例如 
cargo test -p <crate> <filter> -- --nocapture
、聚焦的 unit test、使用 fixture 输入运行 CLI、针对开发服务器编写请求脚本、回放捕获的事件，或者在没有可用 seam 时创建一个小型临时 harness。
  • 缓慢的复现闭环和服务器：在 hc 中运行（
    hc run --bg
    ，然后执行 
    hc wait
    或 
    hc wait --output <ready line>
    ；参见 
    hc
    skill）——绝不要使用 
    &
    、
    nohup
    、
    disown
    或 
    setsid
    。
  • 仅将子 Agent 用于独立调查，并严格限定其 cwd 和具体文件；在其运行期间继续执行其他可运行的探测；报告会自动返回。
  • 对于耗时较长的诊断，使用 
    chains
    skill 保存 chain link，其中包含症状、复现命令、已测试的假设、涉及的文件、id 和下一步操作。
在闭环能够复现 bug，或证明仍需收集更多证据之前，不要继续。

4. Reproduce and minimize

4. 复现并最小化

Confirm the loop matches the user's symptom, not a nearby failure. Then reduce to the smallest file set, command, input, and package, and the shortest log excerpt that proves the problem. For flaky bugs, raise the reproduction rate: repeat, isolate shared state, pin cwd, tune concurrency/stress, record pass/fail counts.
确认闭环与用户描述的症状一致，而不是某个相邻失败。然后将问题缩减到能够证明问题的最小文件集、命令、输入和 package，以及最短的日志摘录。对于 flaky bug，提高复现率：重复执行、隔离共享状态、固定 cwd、调整并发/压力，并记录通过/失败次数。

5. Hypothesize before probing

5. 先提出假设，再进行探测

Non-obvious bugs: 3–5 ranked hypotheses before changing code. Obvious ones: state the single likely cause and its confirming check.
text
Hypothesis: [cause]
Prediction: if true, [specific check] shows [specific result].
Probe: [command/read/log inspection]
"The retry budget is shared across requests; two concurrent fixture calls will exhaust the same counter" is a hypothesis. "State bug" is not.
对于不明显的问题：修改代码前先提出 3–5 个按可能性排序的假设。对于明显的问题：指出最可能的单一原因及其确认检查。
text
假设：[原因]
预测：如果假设成立，[具体检查]将显示[具体结果]。
探测：[command/read/log inspection]
“重试预算由多个请求共享；两个并发的 fixture 调用会耗尽同一个计数器”是一个假设。“状态 bug”不是假设。

6. Probe narrowly

6. 窄范围探测

One hypothesis, one variable per probe. Prefer existing logs/tests/traces before adding instrumentation; tag any added debug output with a unique marker like 
[DEBUG-7f3a]
; probe decision boundaries, never "log everything". Keep notes: hypothesis → probe → result → next.
Rust probes: 
RUST_BACKTRACE=1
, targeted 
RUST_LOG=<module>=debug
, focused assertions, trait impl/feature-flag/cfg inspection, shared state through 
Arc
/locks/caches/globals, behavior with/without concurrency/retries/timeouts. For performance regressions, measure a baseline (command, input, sample size, variance) before fixing; then bisect or profile.
每次探测只验证一个假设、只改变一个变量。添加 instrumentation 前，优先使用现有 logs/tests/traces；为新增的调试输出添加唯一标记，例如 
[DEBUG-7f3a]
；探测决策边界，绝不要“记录所有内容”。保留记录：假设 → 探测 → 结果 → 下一步。
Rust 探测：使用 
RUST_BACKTRACE=1
、定向的 
RUST_LOG=<module>=debug
、聚焦的 assertions，检查 trait impl/feature-flag/cfg，通过 
Arc
/locks/caches/globals 追踪共享状态，以及验证有无 concurrency/retries/timeouts 时的行为。对于性能回归，修复前先测量基线（命令、输入、样本量、方差），然后进行 bisect 或 profile。

7. Fix with a regression guard

7. 修复并添加回归防护

State the minimal fix and what will prove it. After editing: rerun the minimized loop, the original loop, and the narrowest relevant package checks; add a durable regression check when a good test seam exists — if none does, say so and recommend the smallest future validation improvement.
说明最小修复方案以及能够证明修复有效的方法。编辑后：重新运行最小化闭环、原始闭环，以及最窄范围内的相关 package 检查；如果存在合适的 test seam，则添加持久的回归检查——如果没有，应明确说明，并建议未来最小的验证改进方案。

8. Cleanup and report

8. 清理并报告

Remove 
[DEBUG-...]
probes and throwaway harnesses, stop unneeded background processes, reference useful artifacts by id/path. Report: root cause, fix, verified-by, remaining risk / follow-up.
移除 
[DEBUG-...]
探测和临时 harness，停止不再需要的后台进程，并通过 id/path 引用有用的 artifacts。报告应包含：根因、修复方式、验证方式、剩余风险/后续事项。

Pitfalls

常见误区

  • No patching before reproducing unless the user explicitly accepts a speculative fix.
  • No whole-workspace runs when a package-level loop proves the symptom.
  • A passing narrow check counts only after the original repro also passes.
  • Broad subagent sweeps are not "diagnosis"; bound cwd, files, and tool count.
  • 除非用户明确接受推测性修复，否则在复现之前不要打补丁。
  • 当 package 级别的闭环已经能够证明症状时，不要运行整个 workspace。
  • 只有在原始复现也通过后，狭窄检查通过才算有效。
  • 大范围扫描子 Agent 不是“诊断”；必须限定 cwd、文件和工具数量。