superior-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superior Debugging

高级调试

Turn an observed failure into a supported causal explanation, then make the smallest complete repair. Preserve the user's scope and the repository's existing architecture while distinguishing evidence from assumptions.

将观察到的故障转化为有证据支持的因果解释，然后实施最小且完整的修复。在区分证据与假设的同时，遵循用户的范围界定并保留仓库的现有架构。

Define the failure precisely

精确定义故障

Before changing code, establish:

the observed result, expected result, and source of that expectation;
the smallest known reproduction and whether it is deterministic;
the affected versions, environments, inputs, users, or data states;
the last known good state when evidence exists;
impact, urgency, and any unsafe reproduction boundary.

Do not silently redefine expected behavior to match the implementation. If the contract is ambiguous, identify the ambiguity and use repository evidence or user direction before treating either behavior as a defect.

在修改代码之前，明确以下事项：

观察到的结果、预期结果，以及该预期的来源；
已知范围最小的复现方式，以及它是否具有确定性；
受影响的版本、环境、输入、用户或数据状态；
有证据时，最后已知正常的状态；
影响、紧急程度，以及任何不安全的复现边界。

不要悄然重新定义预期行为以迎合现有实现。如果约定不明确，应先指出歧义，并在将任一行为视为缺陷之前，依据仓库证据或用户指示作出判断。

Follow evidence to cause

循证追踪原因

Read references/evidence-driven-diagnosis.md when the cause is uncertain, multiple hypotheses are plausible, or a regression must be narrowed through history or controlled experiments.

Trace the failing path across the boundaries that can own the symptom. Inspect actual values, state transitions, configuration, persistence, external responses, and timing rather than inferring them from nearby code. Maintain a small set of falsifiable hypotheses and run the cheapest discriminating check first.

Separate:

trigger: the input or condition that exposes the failure;
root cause: the violated invariant or incorrect behavior that makes failure possible;
amplifier: retries, caching, concurrency, stale state, or error handling that increases impact;
symptom: the user-visible or operational result.

Do not stop at the first suspicious line, exception site, or correlated event. A stack frame shows where a failure surfaced, not necessarily where it originated.

当原因不明确、存在多个合理假设，或需要通过历史记录或受控实验缩小回归问题范围时，阅读 references/evidence-driven-diagnosis.md。

沿着可能负责该症状的边界，追踪故障路径。检查实际值、状态转换、配置、持久化数据、外部响应和时序，而不是根据附近代码进行推断。维护一组规模较小的可证伪假设，并首先执行成本最低、区分度最高的检查。

区分以下概念：

**触发条件：**暴露故障的输入或条件；
**根因：**使故障成为可能的不变量失效或错误行为；
**放大因素：**扩大影响的重试、缓存、并发、陈旧状态或错误处理；
**症状：**用户可见或运维层面的结果。

不要停留在第一个可疑代码行、异常发生位置或相关性事件上。堆栈帧显示的是故障暴露的位置，而不一定是故障起源。

Diagnose runtime boundaries safely

安全诊断运行时边界

Read references/runtime-and-distributed-failures.md for environment-only failures, asynchronous or concurrent behavior, queues, caches, databases, external services, resource exhaustion, or production telemetry.

Prefer existing logs, traces, metrics, error reports, and safe local reproduction before adding instrumentation.
Redact secrets, tokens, personal data, and sensitive payloads from diagnostics.
Do not experiment on production traffic, mutate shared data, disable safeguards, or increase broad logging without explicit authorization and a rollback plan.
Do not treat a timeout increase, retry, cache clear, process restart, or swallowed exception as a root-cause repair unless the contract proves it is the correct behavior.

对于仅在特定环境中发生、异步或并发、队列、缓存、数据库、外部服务、资源耗尽或生产遥测相关故障，阅读 references/runtime-and-distributed-failures.md。

优先使用现有日志、追踪、指标、错误报告和安全的本地复现，然后再添加检测工具。
从诊断信息中移除密钥、令牌、个人数据和敏感载荷。
未经明确授权和回滚方案，不要在生产流量上进行实验、修改共享数据、禁用安全保护或扩大日志记录范围。
除非约定能够证明其属于正确行为，否则不要将延长超时时间、重试、清空缓存、重启进程或吞掉异常视为根因修复。

Repair at the owning boundary

在责任边界处修复

Once evidence identifies the cause:

state the causal chain in one concise explanation;
change the boundary that owns the violated contract;
preserve compatibility and unrelated behavior;
remove temporary diagnostics that are noisy, sensitive, or no longer useful;
add or update a regression test when practical and credible;
verify the original reproduction and relevant neighboring behavior.

If evidence disproves the suspected code defect, report the actual cause instead of forcing a code change. If the cause remains uncertain, label the result as partial and preserve the next discriminating observation or experiment.

一旦证据确定了原因：

用一段简洁说明陈述因果链；
修改负责违反约定的边界；
保持兼容性和无关行为不受影响；
移除嘈杂、敏感或已无用途的临时诊断代码；
在切实可行且可信的情况下，添加或更新回归测试；
验证原始复现和相关邻近行为。

如果证据否定了疑似代码缺陷，应报告实际原因，而不是强行修改代码。如果原因仍不明确，应将结果标记为部分完成，并保留下一步具有区分度的观察或实验。

Report confidence honestly

如实报告置信度

Report:

symptom and confirmed scope;
evidence inspected and reproduction status;
root cause, with trigger and amplifier separated when relevant;
repair and why it addresses the causal mechanism;
verification performed and its result;
remaining uncertainty, untested environments, and operational follow-up.

Do not claim a production-only incident is resolved solely because a local test passes. State whether the result is reproduced, mitigated, repaired, or still under investigation.

报告以下内容：

症状和已确认的影响范围；
已检查的证据和复现状态；
根因，并在相关时区分触发条件和放大因素；
修复内容及其解决因果机制的原因；
已执行的验证及其结果；
剩余不确定性、未测试的环境和后续运维操作。

不要仅因为本地测试通过，就声称仅在生产环境中出现的事件已经解决。应明确说明结果是已复现、已缓解、已修复，还是仍在调查中。

Combine skills narrowly

有针对性地组合 Skills

Use
```
superior-code-review
```
when the primary task is to assess a change set rather than diagnose an observed failure.
Use
```
superior-logic
```
when the confirmed repair changes domain rules, persistence, state transitions, or API behavior.
Use
```
superior-database
```
when the confirmed cause requires schema, query, transaction, migration, or data-repair work.
Use
```
superior-performance
```
when the confirmed cause leads to measured optimization, capacity analysis, or a performance budget.
Use
```
superior-reliability
```
when the confirmed cause requires resilience, degradation, recovery, alerting, or runbook changes.
Use
```
superior-delivery
```
when the failure belongs to a pipeline, artifact, rollout, or environment-promotion path.
Use
```
superior-testing
```
when regression design, test isolation, or flaky-test diagnosis becomes a primary concern.
Use
```
superior-api-security
```
when the failure reveals an authorization, validation, abuse, token, SSRF, or information-disclosure weakness.
Use
```
superior-docs
```
after a verified material repair or when a durable diagnostic or recovery procedure changes.

Do not broaden diagnosis into unrelated refactoring, observability-platform adoption, performance optimization, or architecture redesign.

当主要任务是评估变更集，而不是诊断观察到的故障时，使用
```
superior-code-review
```
。
当确认的修复会改变领域规则、持久化逻辑、状态转换或 API 行为时，使用
```
superior-logic
```
。
当确认的原因需要处理 schema、查询、事务、迁移或数据修复工作时，使用
```
superior-database
```
。
当确认的原因需要执行有实测依据的优化、容量分析或设定性能预算时，使用
```
superior-performance
```
。
当确认的原因需要调整韧性、降级、恢复、告警或 runbook 时，使用
```
superior-reliability
```
。
当故障属于 pipeline、artifact、rollout 或环境晋级路径时，使用
```
superior-delivery
```
。
当回归测试设计、测试隔离或 flaky-test 诊断成为主要问题时，使用
```
superior-testing
```
。
当故障暴露出授权、验证、滥用、令牌、SSRF 或信息泄露方面的弱点时，使用
```
superior-api-security
```
。
在完成经过验证的重要修复后，或持久化诊断与恢复流程发生变化时，使用
```
superior-docs
```
。

不要将诊断范围扩大为无关重构、可观测性平台采用、性能优化或架构重新设计。