root-cause

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Root Cause

根因分析

Find the smallest causal mechanism or sufficient causal set that explains the observed failure and downstream symptoms. Diagnosis stays separate from triage/review/correction delivery.
A useful model may be:
text
trigger + enabling conditions + propagation + missing containment/detection → observed failure
找出能够解释观测到的故障及下游症状的最小因果机制或充分因果集合。诊断需与分类/评审/修复交付环节分离。
一个实用的模型可参考:
text
trigger + enabling conditions + propagation + missing containment/detection → observed failure

Pin the failure

定位故障

Record exact symptom, expected behavior, first known trigger, candidate/revision or event identity, environment/context, reproducibility, evidence, scope, and read/probe authority. A report, stack trace, correlation, changed artifact, or temporal order is evidence, not a cause.
Use
se-triage
when an engineering/software report still needs issue-validity classification. Use
alaga
only when the diagnosis is settled and the correction is a software/build delivery job; otherwise return the diagnosis to the current correction owner.
Reproduce safely when possible; otherwise pin one equivalent direct observation. Separate primary failure from secondary errors, retries, compensating behavior, and recovery noise.
记录确切症状、预期行为、首个已知触发因素、候选版本/事件标识、环境/上下文、可复现性、证据、影响范围以及读取/探查权限。报告、堆栈跟踪、相关性、变更工件或时间顺序均为证据,而非原因。
若仍需对工程/软件报告进行问题有效性分类,请使用
se-triage
。仅当诊断结果确定且修复工作为软件/构建交付任务时,才使用
alaga
;否则请将诊断结果返回给当前负责修复的人员。
尽可能安全地复现故障;若无法复现,则定位一个等效的直接观测结果。将主故障与次要错误、重试、补偿行为及恢复干扰区分开。

Competing mechanisms

竞争性机制

Write a small hypothesis table. For each hypothesis state trigger/mechanism, enabling conditions, propagation, evidence explained, one distinguishing observation, and the smallest safe probe.
Read probe commands when bounded source/history/Git evidence can discriminate hypotheses. Prefer existing observations, tests, logs, traces, configuration, history, measurements, and reversible diagnostics that fit the domain.
Choose each next observation or intervention for its ability to distinguish the live hypotheses, not because a preferred debugging ritual exists. Control material confounders where practical. Vary one factor at a time only when that probe can actually discriminate the mechanism; when interactions or coupled conditions are plausible, design the observation/probe to expose those interactions rather than pretending the factors are independent.
For a proposed causal explanation establish:
  1. Explanatory sufficiency — the proposed mechanism/set explains or reproduces the observed failure and material downstream symptoms without an unresolved causal gap.
  2. Factor support — each claimed causal factor has discriminating evidence showing its contribution in the relevant context. When feasible, removing/controlling a factor should change the outcome or a predicted mediator as expected.
  3. Conditionality and alternatives — do not label a factor globally necessary when another sufficient pathway, interaction, or context can produce the same failure. State whether the factor is necessary for this observed pathway, contributing, enabling, interacting, or unresolved.
A factor lacking discriminating support is contextual/contributing/unresolved, not a confirmed root cause merely because it occurred before the failure.
编写一个小型假设表格。针对每个假设,说明触发因素/机制、使能条件、传播路径、已解释的证据、一个具有区分度的观测点以及最小的安全探查方式。
当有限的源代码/历史记录/Git证据可用于区分假设时,请阅读探查命令。优先使用符合领域要求的现有观测结果、测试、日志、追踪信息、配置、历史记录、测量数据及可逆诊断方法。
选择下一个观测或干预措施时,应基于其区分当前假设的能力,而非遵循偏好的调试惯例。在可行情况下控制实质性混杂因素。仅当探查确实能区分机制时,才每次只改变一个因素;若存在交互作用或耦合条件的可能性,则设计观测/探查以暴露这些交互作用,而非假设因素相互独立。
对于提出的因果解释,需确认以下三点:
  1. 解释充分性——所提出的机制/集合能够解释或复现观测到的故障及实质性下游症状,且无未解决的因果缺口。
  2. 因素支撑——每个声称的因果因素均有区分性证据表明其在相关场景中的作用。在可行情况下,移除/控制该因素应能如预期般改变结果或预测的中间变量。
  3. 条件性与替代性——当存在其他充分路径、交互作用或场景可导致相同故障时,请勿将某一因素标记为全局必要条件。需说明该因素在当前观测路径中是必要的、起促进作用的、使能的、交互的还是未解决的。
缺乏区分性支撑的因素属于背景/促进/未解决因素,不能仅因它在故障发生前出现就被认定为已确认的根因。

Stop on evidence

基于证据停止

Continue only while another safe observation can materially update the causal model. Stop when remaining hypotheses cannot be distinguished, no safe probe can change the diagnosis, required environment/observability/authority is unavailable, or the failure cannot be reproduced and no equivalent direct evidence exists.
Do not perform correction attempts inside Root Cause.
仅当另一个安全观测能够实质性更新因果模型时,才继续诊断。当剩余假设无法区分、无安全探查可改变诊断结果、所需环境/可观测性/权限不可用,或故障无法复现且无等效直接证据时,停止诊断。
请勿在根因分析环节尝试修复操作。

Result

结果

Return one:
  • CONFIRMED_ROOT_CAUSE
    — minimal causal mechanism/set and discriminating evidence are sufficient for the observed failure/path;
  • DIAGNOSED_BUT_UNPROVED
    — best explanation has a material causal/evidence gap;
  • EVIDENCE_BLOCKED
    — named evidence/environment/authority/observability gap;
  • NOT_REPRODUCED
    — pinned failure not observed and no equivalent direct evidence.
Include failure identity, minimal mechanism/set, per-factor evidence and causal role, interactions/alternative sufficient paths when material, contributing/contextual/unresolved factors, propagation/containment, decisive evidence, falsified alternatives, affected boundary, confidence limits, and smallest useful next action.
When a durable diagnosis is needed, use the existing/user-selected destination; use
akosile
only when that destination is a repository-scoped
.qp
workspace. Use
html-artifact
only when a substantial terminal diagnosis benefits from a visual view.
返回以下结果之一:
  • CONFIRMED_ROOT_CAUSE
    ——最小因果机制/集合及区分性证据足以解释观测到的故障/路径;
  • DIAGNOSED_BUT_UNPROVED
    ——最佳解释存在实质性因果/证据缺口;
  • EVIDENCE_BLOCKED
    ——存在明确的证据/环境/权限/可观测性缺口;
  • NOT_REPRODUCED
    ——已定位的故障未被观测到,且无等效直接证据。
需包含故障标识、最小机制/集合、各因素的证据及因果角色、实质性的交互作用/替代充分路径、促进/背景/未解决因素、传播/遏制机制、决定性证据、已证伪的替代假设、影响边界、置信限度以及最有用的下一步操作。
当需要持久化诊断结果时,请使用现有/用户选定的目标;仅当该目标为仓库范围的
.qp
工作区时,才使用
akosile
。仅当重要的终端诊断可从可视化视图中获益时,才使用
html-artifact