rca-report

RCA 报告

撰写的事后复盘应当可复现、分层清晰且对实际运维有用，而不只是叙述经过。一份优秀的 RCA 能让未来的工程师（或未来的你）了解事故、验证修复是否有效，并避免重蹈覆辙。本技能涵盖调查流程（事故发生后趁记忆犹新时收集哪些信息）和报告本身。

适用场景

• 发生了生产事故、服务中断或险情，需要记录
• 某个管道、服务或系统悄无声息地发生故障，用户刚刚解决了问题
• 用户需要事后复盘、RCA 或事故报告
• 调查进行到一半：用户正在调试问题，并希望在证据出现时获得整理证据的帮助

如果事故仍在持续恶化，而用户只想获得修复方面的帮助，请跳过此技能——先修复，再记录。

输出位置

将报告保存到当前工作目录下的 <topic>-rca-<YYYY-MM-DD>.md，其中：

• <topic> 是故障系统的简短 kebab-case 标识符（例如 debezium、auth-service、kafka-consumer-lag）
• <YYYY-MM-DD> 是事故日期（事故发生的日期），不一定是今天

示例：debezium-rca-2026-05-05.md、auth-500s-rca-2026-04-12.md

两阶段工作流

阶段 1 — 调查（收集证据）

开始写作前，先与用户一起逐项检查 references/investigation-checklist.md。目标是确认具体且可复现的事实——时间戳、版本号、准确的 LSN/ID/错误字符串、命令输出——趁系统状态仍可观察时及时收集。记忆会迅速衰退；日志会轮转；复制槽会前进。现在收集，之后再写。

即使用户说“我已经修好了”，也不要跳过此阶段——修复后的状态证据（健康的 confirmed_flush_lsn 持续前进、测试行流经 Kafka、新容器日志显示“streaming from latest xlogpos”）才能证明问题确实得到了解决。这份证据正是可信的 RCA 与单纯故事之间的区别。

如果用户已经有事故发生时的笔记/转录/滚动记录，先从中提取信息，再提问。不要让他们重新输入对话中已有的内容。

阶段 2 — 撰写报告

使用 templates/rca-report.md 作为结构框架。根据阶段 1 收集的证据逐节填写。完成前，再依据 references/quality-rubric.md 进行验证。

什么样的 RCA 才算真正出色

这项技能参考的 Debezium RCA 之所以有效，是因为它具备以下要素：

1. 为每个可观测事件标注 UTC 时间戳的时间线——“连接器卡住了约 18h”是叙述；“2026-05-04 09:54:16 Postgres 终止了复制连接”才是证据。始终优先采用精确的表述。

2. 全面标识系统的基础设施表——版本、主机名、可用区、连接器名称、主题名称、槽名称。六个月后阅读这份文档的人，也应该能毫无歧义地找到确切的资源。

3. 从用户、系统、数据和 SLA 维度量化影响——模糊的影响描述（“一些客户受到了影响”）对严重性评估毫无帮助。应以具体数字说明用户可见的影响、内部系统降级情况、数据完整性状态，以及 SLA / 财务成本。如果某个数字未知，应明确说明，而不是跳过该维度。

4. 分层进行根因分析——不仅要说明出了什么问题，还要说明：

   • 主要原因（触发事件）
   • 为何看起来健康（是什么掩盖了故障——这通常是最有价值的部分）
   • 次要机制（促成问题的门控、重试和内部状态）

5. 记录包含实际值的状态快照——预期状态与观测状态之间的差异，能让诊断一目了然。confirmed_flush_lsn = 1/AD5B16C0 (pre-restore stale value) 旁边列出 pg_current_wal_lsn = 1/ADC4B740 (current)，两行就说明了全部情况。根据你所处的领域，记录类似的差异（队列深度、错误率、版本不匹配、架构漂移等）。

6. 将变通方案 / 临时缓解措施与解决方案分开记录——在完全理解根因之前，用快速、低风险的操作先止住问题。变通方案和解决方案回答的是不同问题：变通方案 = 下次凌晨 3 点再次发生时，值班人员该怎么做；解决方案 = 如何永久结案。记录变通方案的效果、风险，以及应用它的触发条件。

7. 说明解决步骤的顺序依据——不能只写“我运行了这些命令”，还要说明为什么按此顺序操作。如果由于内存中的状态，步骤 4 必须在步骤 3 之后执行，就要写明。遇到问题的下一个人会先尝试直观的顺序并失败；应记录为什么直观的顺序行不通。

8. 通过“5 个为什么”追溯到系统性缺口——只有当分析最终指向缺失的防护措施（告警 / 审查 / 测试 / 知识），而非技术触发因素时，这条链才有用。每个“为什么”都应聚焦于不同的机制——相邻步骤只是同义反复，说明内容是在凑数。最终答案应能直接对应下方的一条建议。

9. 设置“哪些方法没有奏效”一节——记录行不通的方法。未来的你可能会想尝试同样的方法。Debezium RCA 中“删除槽 + 重建连接器但不重置偏移量”这一项非常有价值——这是最直观的修复方法，却会悄无声息地失败。

10. 将诊断命令整理成可直接复制粘贴的代码块——该领域下一次发生事故时，其中 80% 的命令都能重复使用。命令应可直接运行，而不是伪代码。

11. 提供验证证据——证明修复有效且问题没有复发。端到端测试数据流。槽延迟趋于稳定。错误率回到基线。并提供修复后状态的实际值。

12. 按紧急程度分类列出建议——立即处理（告警 / 监控）、流程（运行手册、沟通）、配置（设置变更）。分类能促使用户考虑时间安排，而不只是罗列“待办事项”。

应避免的反模式

• 时间线模糊：“第二天早上我们注意到……”——什么时候？“注意到”具体指什么？谁看到了什么？
• 根因分析只有一层：只停留在触发事件，却不解释掩盖机制。如果系统看起来运行正常，那么在整个故障期间，这种掩盖机制本身就是根因。
• 没有说明理由的解决方案：只列出命令，却不解释为什么按这个顺序执行，或为什么采用这种方法。这是运行手册，不是 RCA。
• 含糊的建议：“改进监控”无法付诸行动。“当 pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn) > 100MB 持续 5+ 分钟时发出告警”才是可执行的建议。
• 跳过失败的尝试：每个没有记录的死胡同，都会成为后来者的陷阱。
• 没有验证：没有证据证明修复确实有效就关闭报告。RCA 就是这样沦为传说的。

工作流

1. 确认事件已解决或已控制。 如果事件仍在持续发生，请暂缓使用此技能。
2. 先挖掘已有上下文。 对话记录、滚动缓冲区、先前的笔记——在询问用户之前，尽可能提取所有信息。
3. 按调查清单逐项检查（references/investigation-checklist.md）。通过提出有针对性的问题或运行诊断命令来填补信息缺口。即使是“小型”事件也要这样做——这种结构能确保分析深入。
4. 捕获状态快照。 如果系统可以访问，现在就获取当前正常状态的数值（复制槽滞后、队列深度、错误率等）——这些数值应写入验证部分。错过了，就无法证明修复有效。
5. 使用 templates/rca-report.md 起草报告。 填写每个部分；如果某部分确实不适用，请写“ N/A — [reason]”，不要删除该部分。
6. 根据质量标准核验（references/quality-rubric.md）。提交前修复所有不符合标准的问题。
7. 在当前工作目录（CWD）中保存为 <topic>-rca-<YYYY-MM-DD>.md。
8. 向用户展示文件路径，并提出可以逐项讲解报告内容。 除非用户提出要求，否则不要把整份报告贴到聊天中——他们会阅读文件。

语气

贴合操作者的表达风格：技术性强、简洁、以证据为依据。每个部分先给出结论，再说明理由。不要使用企业式的含糊措辞（“可能造成了一些影响”）——直接陈述发生了什么。不要归咎于个人——聚焦系统缺陷，而不是个人。Debezium RCA 是参考范例；保持同样直截了当的风格。