awesome-root-cause

根因分析

找出事故、反复发生的故障或流程问题的真正原因——这类问题没有失败测试可用于复现——并推动实施持久有效的对策。以无责为设计原则：目标是解决系统性问题，而不是追究个人责任。

何时使用此技能，而非 awesome-bug-fix 或 awesome-performance-audit

• 使用此技能处理事故复盘、“这个问题总是反复出现”、数据质量、交接或部署流程问题，以及险些酿成事故的情况。问题出在流程、环境或协作上，无法仅靠运行操作并观察故障来分析。
• 使用 awesome-bug-fix 处理有复现步骤的具体代码缺陷。如果你能编写一个失败测试，就使用该技能；没有可运行的测试时，再使用此技能。
• 使用 awesome-performance-audit 处理运行缓慢、内存泄漏或延迟飙升的服务或页面，即使这类情况按固定周期反复发生；应先进行测量，再追问原因。

如果问题涉及多个方面（例如，流程缺陷导致代码 Bug 上线），就用 awesome-bug-fix 修复 Bug，并用此技能分析导致其上线的流程。

工作流

1. 界定问题

将问题描述为可观察到的差距，而非解决方案或责任方：当前状况与预期状况、问题何时开始、发生频率、影响范围，以及判断依据（证据——日志、工单、时间线）。如果无法具体描述差距，请先收集更多信息，再进行分析。

根据记录（日志、工单、部署历史、聊天记录）而非记忆构建时间线，并分别标出四个时间点：开始、检测、缓解、解决。从开始到检测所需的时间本身就是一项发现。信号会滞后：警报会在评估窗口结束后触发；指标数据点会标记其聚合周期的一端（通常是开始），而非事件实际发生的时间；日志会延迟写入；审计事件会在操作发生后才到达。因此，开始时间应取原始数据中最早出现异常的时间，而不是警报触发时间。若记录无法解释时间线中的某段空白，应将其作为问题交由团队调查，而不是凭猜测填补。

自上而下缩小影响范围：环境或账户，然后是区域、服务、操作，最后是资源。同一层级的多个单元同时受影响时，应先查找它们共有的依赖项（网络、DNS、身份验证、共享流水线），再深入调查其中任何一个单元。

2. 扩大候选原因范围（鱼骨图）

深入调查前，先检查六类原因，避免只盯着显而易见的原因——人员、流程、技术、环境、方法、材料。逐类列出可能的促成因素。根因更多出在流程或方法，而非技术；纯技术原因是例外，不应默认如此。

3. 深入分析每个真实候选原因（5 个为什么）

对每个保留下来的候选原因，沿着原因链不断追问“为什么”。遵循两条规则：

• 找到系统性缺口时停止，不要归咎于某个人。如果原因链最终落在“人为失误”上，就继续追问：“为什么会发生这种失误？”——真正的根因是缺少验证、缺少自动化，或流程不明确。值得找出的，是无法通过改变某个人来解决的原因。
• 次数并非固定。找到一种原因后，如果消除它就能防止这类问题，就停止——不管追问了 3 次还是 7 次。不要为了凑够 5 次而硬凑。

每条原因链的终点都应是有证据支撑、而非仅凭断言的候选根因。

并行深入调查（多个候选原因）。鱼骨图排查（步骤 2）和 5 个为什么分析（步骤 3）彼此独立，都是只读的证据调查——按原因类别或保留下来的候选原因，分别分派一个子 Agent，让每个 Agent 收集各自的日志、工单和时间线。步骤 4 设为屏障：主 Agent 对收敛到同一系统性缺口的原因链去重，应用“同类问题，而非单个实例”的检验，并对所有候选措施进行排序——每个原因链的 Agent 可以提出候选措施，但不得撰写最终的改进措施。资源预检（分派前）：每轮只安排少数几个子 Agent；如果每个 Agent 都要运行浏览器、语言服务器或测试，则进一步减少；如果机器的 CPU 或内存已经吃紧，就改为串行执行；如果运行环境本身限制了子 Agent 的并发数，则遵从其限制。

4. 改进措施（优先采用防错法）

针对每个已确认的根因，优先采用能从结构上防止问题再次发生的措施，而不是“多加小心”：

• 让错误状态无法出现（设置防护条件、必填字段或 CI 检查），而不是仅仅提醒；
• 将出错的人工步骤自动化；
• 明确或删除含糊不清的流程。 按影响 × 可行性 ÷ 工作量为修复措施排序。为每项措施指定负责人。

5. 用 PDCA 验证

将每项改进措施视为一项实验，而不是既定成果：

• 计划——在做出任何更改之前，明确一项可量化的成功标准（“4 周内零复发”“交接错误从每周 3 次降至 0 次”）。
• 执行——实施一项改进措施。
• 检查——根据成功标准进行衡量；使用服务端或独立信号，而非自我报告。
• 处理——保留、调整或撤销。 如果经过 3 个周期仍无改善，说明根因判断有误——返回步骤 3。

输出：单页 A3

提交一份精简报告，不要写成长篇大论：

Title / date / owner

Background       — why this matters, in 1–2 lines
Current condition — the gap, with evidence (metric, timeline: onset, detection, mitigation, resolution)
Target           — the measurable desired state
Root cause(s)    — from the 5-Whys chains, each with its evidence
Contributing factors — conditions that widened or prolonged the impact but would not alone have caused it (slow detection, missing runbook)
Countermeasures  — fix | owner | prevents recurrence how
Verification plan — success criterion + PDCA check date
Follow-up        — open items, what to watch

这份复盘报告读起来如何

复盘报告会由当时不在场的人阅读，也会在一年后由下一位值班人员阅读。文档应包含带时区的绝对时间戳、准确的故障机制、坦诚记录的错误排查方向，以及明确由人负责的行动项。团队的事故模板可以作为容器；问题的迹象在于其中的填充内容。行文规则（awesome-humanize-en/references/domain-postmortems.md 包含完整的迹象表；如果没有该技能，以下规则就是全部标准）：

• 无责不等于没有主体。“犯了错误”“变更已部署”，却完全不提执行者，都是含糊其辞。写明系统和职责角色：“部署流水线在验证运行前就推送了配置”。
• 时间线要保留错误的排查方向。花在错误假设上的 40 分钟，是文档中最有启发性的部分，也是复盘报告最常省略的部分。使用绝对时间，并注明一次时区。
• 说明代码或配置层面的机制：确切的查询、标志、限制值或竞争窗口。如果还没人知道，那应该作为团队的问题，而不是用文字掩盖的空白。
• 行动项应是有负责人和截止日期的变更。“改进监控和沟通”不算行动项；“在队列深度 > 10k 时添加警报（负责人：基础设施团队，截止日期：09-15）”才算。
• 不要自夸。“团队迅速发现了……”——时间戳足以体现速度，让它们自己说明。
• 明确陈述你认定的因果链，并将真正未知的部分标记为未知。“多种因素可能造成了影响”是在需要判断的地方回避判断。
• 先用数字说明影响（持续时间、失败请求数、受影响用户数、已知时的损失金额），再做叙述。数字应来自事故数据，不能为了显得完整而取整。
• 模板中的每个部分都应有其篇幅价值。“哪些方面做得好”如果没有内容，就诚实地写一句，或者删除，不要为了完整而凑成一段。
• 到行动项为止。不要以关于可靠性文化的说教式结论收尾。任何完全不承认错误判断的复盘报告，都还没有真正写出来。

防护原则

• 不归咎个人。写明系统和步骤，而不是个人。“部署流程没有预发布环境检查关卡”，而不是“X 未经测试就部署了”。
• 证据优先于叙述。每个根因都要引用证明依据（日志行、工单、时间线条目）。看似合理的解释在证据支持之前都只是一个假设。
• 缺少依据，就不要下结论。如果缺少确定根因所需的时间线或数据，就说明缺少什么，并停留在候选原因上——不要为了给报告收尾而编造一个整洁的根因。
• 解决一类问题，而非单个案例。如果对策只能修复这一次事件，不能解决这一类问题，那就还不完整——请明确指出。

示例 A3

重复发生的故障：夜间部署在迁移步骤回滚。

Nightly deploy failures / 2026-03-14 / owner: platform on-call

Background       — 6 of 14 nightly deploys rolled back in two weeks; each burns ~40 min of on-call time and delays the release train.
Current condition — 6/14 failed, all at the migration step, all with `lock timeout` on `orders` (pipeline runs 812, 817, 819, 823-825; timeline in #deploys).
Target           — zero migration-caused rollbacks across 4 consecutive weeks.
Root cause(s)    — the nightly analytics job holds a long transaction on `orders`, and nothing sequences it against the deploy, so overlap is chance (run logs 812/817/823 overlap by 4-11 min). The migrate step sets no lock wait, so one contended statement fails the whole deploy (`deploy.yml`, migrate step).
Countermeasures  — analytics publishes a completion gate the deploy waits on | platform | overlap becomes impossible, not unlikely. Migrate step sets an explicit lock timeout and retries once | platform | contention degrades to a retry, not a rollback.
Verification plan — criterion: 0 migration rollbacks over 4 weeks, read from pipeline run records, not on-call recall; PDCA check 2026-04-11.
Follow-up        — audit other jobs holding long transactions on `orders`; open question: can analytics move off the primary?