Back to Details

write-a-postmortem

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write a postmortem

撰写 postmortem

The platform 
/open-knowledge
skill still governs every markdown operation here — folder scope, the read/write tool surface, linking, and preview. This skill layers postmortem craft on top of it; it does not replace those rules.
A postmortem is not a status update and not a blame ledger. It is a durable, blameless reconstruction of one incident, built from evidence, that makes the system's failure mode legible and produces action items someone will actually verify. The value compounds only when postmortems that share a subsystem link to each other — that is how a repeat class stops being invisible.
This pack scaffolds 
proposals/
, 
decisions/
, 
specs/
, 
postmortems/
, and 
guides/
at the project root. Postmortems live in 
postmortems/
, one file per incident, filename 
YYYY-MM-DD-name.md
, template id 
postmortem
. Action items that are guide-shaped produce 
runbook
stubs in 
guides/
.
The knowledge base is markdown owned by OpenKnowledge MCP. Read and list in-scope markdown with 
exec
(
exec("ls -A postmortems/")
, 
exec("cat postmortems/2024-03-02-auth-outage.md")
, 
exec("grep -rln failover .")
) and 
search({ query: "..." })
; create and edit with 
write
and 
edit
; inspect the link graph with 
links
. Never use native Read/Edit/Grep/Glob/
cat
on in-scope markdown. Source code, logs, dashboards, deploy history, and chat transcripts are OUTSIDE the knowledge base — read those with the host's native tools. Links are plain markdown relative links 
[db failover](./guides/db-failover.md)
— never backticked, never HTML anchors.
这里的每项 markdown 操作仍由平台 
/open-knowledge
skill 管理——包括目录范围、读/写工具接口、链接和预览。本 skill 在这些规则之上叠加 postmortem 的撰写方法，并不会取代这些规则。
postmortem 不是状态更新，也不是追责台账。它是一份基于证据、对单次事故进行持久且无责的重建，能够让读者理解系统的失效模式，并产出真正会有人验证的改进项。只有当共享同一子系统的 postmortem 相互链接时，价值才会不断累积——这正是重复发生的问题类别不再隐于无闻的方式。
该 pack 会在项目根目录搭建 
proposals/
、
decisions/
、
specs/
、
postmortems/
和 
guides/
。postmortem 存放在 
postmortems/
中，每次事故对应一个文件，文件名格式为 
YYYY-MM-DD-name.md
，模板 ID 为 
postmortem
。以 guide 形式呈现的改进项会在 
guides/
中生成 
runbook
存根。
知识库是由 OpenKnowledge MCP 管理的 markdown。使用 
exec
读取和列出范围内的 markdown（
exec("ls -A postmortems/")
、
exec("cat postmortems/2024-03-02-auth-outage.md")
、
exec("grep -rln failover .")
），并使用 
search({ query: "..." })
搜索；使用 
write
和 
edit
创建及编辑；使用 
links
检查链接图。对于范围内的 markdown，绝不要使用原生 Read/Edit/Grep/Glob/
cat
。源代码、日志、dashboard、部署历史和聊天记录位于知识库之外——应使用宿主环境的原生工具读取。链接使用普通 markdown 相对链接 
[db failover](./guides/db-failover.md)
——绝不要放在反引号中，也不要使用 HTML anchor。

Step 0 — Blamelessness gate (stated first because it constrains every later step)

步骤 0——无责性检查（之所以放在最前，是因为它约束后续每一步）

Blameless is a mechanical discipline, not a slogan you paste in the header. If you cannot follow these rules mechanically, the document is not blameless no matter what it says at the top.
  • Name systems and roles, never individuals. "the deploy pipeline," "the on-call engineer," "the release process" — not "Alice," not "the new hire." A named person turns readers defensive and the analysis stops.
  • Write the system's affordance, not the person's action. "The deploy pipeline allowed an unreviewed config to reach production" — not "Alice deployed an unreviewed config." The grammatical subject is the system that permitted the outcome. If your sentence's subject is a person, rewrite it until it is a system.
  • Treat every human action as the reasonable action given the information available at that moment. Nobody caused the incident by being careless. Someone did the sensible thing with the signals they had. The analytical question is never "why did they do that?" — it is "what made that look like the right move at the time?" A dashboard that read green, an alert that never fired, a runbook that said to do exactly that. Find the thing that made it reasonable; that thing is a contributing factor.
HARD GATE. If the user's framing is blame-seeking — "write up how Alice broke prod," "document who screwed up the deploy" — do not comply as asked. Say so plainly, reframe to the system question, and only then write. Example reframe: "I'll write this blamelessly — the useful question isn't who pushed the config but what let an unreviewed config reach production. That's the finding that prevents a recurrence." Producing a named-culprit document because the user asked for one is the single worst failure this skill can commit; it poisons the postmortem culture the document is supposed to build.
无责性是一种需要机械执行的纪律，而不是贴在标题里的口号。如果无法严格遵守这些规则，那么无论文档顶部写什么，它都不是无责的。
  • 只写系统和角色，绝不写个人。 “部署流水线”、“值班工程师”、“发布流程”——而不是“Alice”或“新员工”。点名个人会让读者产生防御心理，分析也会随之停止。
  • 描述系统所提供的条件（affordance），而不是个人的行为。 “部署流水线允许未经审查的配置进入生产环境”——而不是“Alice 部署了未经审查的配置”。句子的主语必须是促成结果的系统。如果句子的主语是人，就持续改写，直到主语变成系统。
  • 把每个人的行为都视为在当时可获得的信息下合理的行为。 没有人因为粗心而引发事故。在当时掌握的信号下，有人做了看似合理的事。分析问题绝不是“他们为什么这么做？”，而是“什么让这件事在当时看起来是正确选择？”一个显示为绿色的 dashboard、一条从未触发的告警，或一份明确要求如此操作的 runbook。找出让它显得合理的东西；那个东西就是促成因素。
硬性门槛。 如果用户的表述意在追责——例如“写一份说明 Alice 是如何搞坏 prod 的”、“记录是谁搞砸了部署”——不要按原要求执行。明确说明这一点，将问题重构为系统层面的问题，然后再动笔。示例重构：“我会以无责方式撰写——有用的问题不是谁推送了配置，而是什么让未经审查的配置得以进入生产环境。这项发现才能防止事故复发。”如果用户提出要求就生成点名指责者的文档，这是本 skill 可能犯下的最严重错误；它会破坏 postmortem 本应建立的复盘文化。

Step 1 — Gather evidence before you narrate

步骤 1——先收集证据，再叙述

You cannot write a timeline from memory and call it a postmortem. Gather first, narrate second.
Pull, using the host's native tools (these live outside the knowledge base):
  • Alerts and monitoring — what fired, when, and what did not fire that should have.
  • Deploy and release history — what shipped in the hours before, and the exact commit/config.
  • Dashboards and metrics — error rate, latency, saturation, the graphs that show onset and recovery.
  • Chat transcripts and the incident channel — timestamps of human decisions and the reasoning in the moment.
  • The code and config as it stood at incident time — not as it stands now; check out or read the state at the incident SHA.
HARD GATE — no timeline entry without a source you can point at. Every timeline line cites its evidence: an alert ID, a deploy timestamp, a graph, a chat message time. If you are reconstructing a moment from someone's recollection and have no artifact, you may still include it — but label it inline: 
(reconstructed from recollection, no artifact)
. A postmortem whose timeline silently blends logged fact with memory is worse than one that admits the gap, because the reader cannot tell which numbers to trust.
不能凭记忆拼出时间线，然后将其称为 postmortem。先收集，再叙述。
使用宿主环境的原生工具拉取以下信息（这些内容位于知识库之外）：
  • 告警与监控——哪些告警触发、何时触发，以及哪些本应触发却未触发。
  • 部署与发布历史——故障发生前数小时内发布了什么，以及确切的 commit/config。
  • dashboard 与指标——错误率、延迟、饱和度，以及展示故障开始与恢复过程的图表。
  • 聊天记录与事故频道——人工决策的时间戳，以及当时的判断依据。
  • 事故发生时的代码与配置——而不是当前版本；应检出或读取事故 SHA 对应的状态。
硬性门槛——时间线中的任何条目都必须有可指明的来源。 每一条时间线记录都要引用其证据：告警 ID、部署时间戳、图表或聊天消息时间。如果某个时间点只能依据某人的回忆重建且没有制品，仍可写入，但必须在行内标注：
(reconstructed from recollection, no artifact)
。如果 postmortem 的时间线悄悄混合了有日志记录的事实与记忆，那么它比坦承缺口更糟糕，因为读者无法判断哪些信息值得信任。

Step 2 — Scan prior postmortems for the same subsystem

步骤 2——扫描同一子系统的历史 postmortem

Before writing, find out whether this already happened.
  1. exec("ls -A postmortems/")
    — see every prior incident at a glance.
  2. search({ query: "<subsystem> <failure mode>" })
    — semantic match on the affected component (e.g. "database failover replication lag").
  3. exec("grep -rln <subsystem-keyword> postmortems/")
    — exact-term sweep for the service, the error, the mechanism.
  4. exec("cat postmortems/<candidate>.md")
    on the 1–3 closest matches — read their Root cause and Action items.
If this is a repeat of a class already documented, that is the most important finding in the entire document — and it belongs in the Summary, not buried in Related. A recurrence means a prior action item did not land, or landed and did not prevent recurrence. State it in the first two sentences: "This is the third connection-pool exhaustion incident in the payments service (see 2024-01-11, 2024-03-02); the action item from the second was never completed." Repeat classes are where postmortems earn their keep — surface them loudly.
动笔前，先确认这是否已经发生过。
  1. exec("ls -A postmortems/")
    ——一眼查看所有历史事故。
  2. search({ query: "<subsystem> <failure mode>" })
    ——对受影响组件进行语义匹配，例如“数据库故障转移 复制延迟”。
  3. exec("grep -rln <subsystem-keyword> postmortems/")
    ——按服务、错误或机制进行精确词项扫描。
  4. 对 1–3 个最接近的匹配项执行 
    exec("cat postmortems/<candidate>.md")
    ——阅读其根因和改进项。
如果这是已有记录的问题类别的重复发生，那就是整份文档中最重要的发现——它应放在摘要中，而不是埋在相关文档里。 重复意味着之前的改进项没有落地，或者已经落地却未能阻止问题再次发生。应在开头两句话中直接说明：“这是 payments 服务第三次发生连接池耗尽事故（见 2024-01-11、2024-03-02）；第二次事故的改进项从未完成。”重复发生的问题类别正是 postmortem 发挥价值的地方——要明确而突出地呈现。

Step 3 — Create the postmortem from the template

步骤 3——根据模板创建 postmortem

write({ document: { path: "postmortems/YYYY-MM-DD-name.md", template: "postmortem" } })
  • The date is the incident date, not today's. If the outage was 2024-03-02, the filename is 
    postmortems/2024-03-02-name.md
    even if you write it a week later.
  • name
    is a short kebab slug of the affected system and failure: 
    payments-pool-exhaustion
    , 
    auth-cert-expiry
    , 
    search-index-corruption
    .
  • The 
    postmortem
    template scaffolds the SRE shape: Summary / Timeline / Root cause / What went well / Action items. Fill each in the steps below; do not invent a different structure.
write({ document: { path: "postmortems/YYYY-MM-DD-name.md", template: "postmortem" } })
  • 日期是事故发生日期，而不是今天的日期。 如果故障发生于 2024-03-02，即使一周后才撰写，文件名仍应为 
    postmortems/2024-03-02-name.md
    。
  • name
    是受影响系统与故障的简短 kebab slug，例如 
    payments-pool-exhaustion
    、
    auth-cert-expiry
    、
    search-index-corruption
    。
  • postmortem
    模板会搭好 SRE 结构：摘要（Summary）/ 时间线（Timeline）/ 根因（Root cause）/ 做得好的事项（What went well）/ 改进项（Action items）。按以下步骤填写每个部分；不要自行发明其他结构。

Step 4 — Summary: impact first, cause second

步骤 4——摘要：先写影响，再写原因

The Summary is read by people who will never read the rest. Write it for the org, not for the on-call engineer.
  • Lead with user-visible impact: who was affected, how, and for how long. "For 47 minutes, roughly 12% of checkout attempts failed with a 500." Not "the connection pool saturated."
  • Then one sentence of cause, plain: "A config change halved the pool size while traffic was at peak; the pool exhausted and requests queued past timeout."
  • If Step 2 found a repeat class, it goes here (see Step 2).
A summary that leads with the technology ("the connection pool saturated at 14:03") and buries the impact is written for engineers, not for the organization that needs to weigh the incident. Impact is the currency; state it first and in human terms.
许多读者只会阅读摘要，不会阅读其余内容。摘要应面向组织，而不是值班工程师。
  • 先写用户可感知的影响：哪些用户受到影响、如何受到影响、持续多久。“47 分钟内，约 12% 的结账请求因 500 错误而失败。”而不是“连接池已饱和。”
  • 然后用一句话说明原因，且要通俗易懂：“一次配置变更在流量高峰期将池大小减半；连接池耗尽，请求排队并超过超时时间。”
  • 如果步骤 2 发现重复类别，在这里说明（见步骤 2）。
如果摘要以技术现象开头（“14:03 连接池饱和”），却把影响埋在后面，那么它写给的是工程师，而不是需要评估事故的组织。影响才是最重要的信息；应首先用面向人的语言说明。

Step 5 — Timeline: timestamped, sourced, with the detection gap made explicit

步骤 5——时间线：带时间戳、来源，并明确暴露检测缺口

Reconstruct the incident chronologically. Every entry: a timestamp with time zone, what happened, and the evidence it came from.
- 13:52 UTC — Config change #4821 merged, halving `pool.max` from 200 to 100. (deploy log, PR #4821)
- 14:03 UTC — Checkout error rate crosses 5%. (Grafana, checkout-errors panel)
- 14:19 UTC — First page fires to on-call. (PagerDuty incident #9917)
- 14:26 UTC — On-call acknowledges, begins investigating a suspected upstream issue. (incident channel)
- 14:41 UTC — Config change identified as cause; rollback initiated. (incident channel)
- 14:50 UTC — Error rate returns to baseline. (Grafana)
  • Call out detection time and mitigation time explicitly. Mark the entry where the incident began, where it was detected, and where it was mitigated.
  • The gap between incident start and detection is usually the most actionable number in the document. Here: onset 14:03, first page 14:19 — sixteen minutes blind. Name that gap in prose right after the timeline: "Detection lagged onset by 16 minutes; there was no alert on checkout error rate, only on host CPU." That sentence is often the source of the highest-leverage action item.
  • Keep entries factual and sourced. Analysis goes in Root cause, not here.
按时间顺序重建事故。每条记录都要包含：带时区的时间戳、发生了什么，以及证据来源。
- 13:52 UTC — Config change #4821 merged, halving `pool.max` from 200 to 100. (deploy log, PR #4821)
- 14:03 UTC — Checkout error rate crosses 5%. (Grafana, checkout-errors panel)
- 14:19 UTC — First page fires to on-call. (PagerDuty incident #9917)
- 14:26 UTC — On-call acknowledges, begins investigating a suspected upstream issue. (incident channel)
- 14:41 UTC — Config change identified as cause; rollback initiated. (incident channel)
- 14:50 UTC — Error rate returns to baseline. (Grafana)
  • 明确指出检测时间和缓解时间。 标记事故开始、被检测到以及得到缓解的对应条目。
  • 事故开始与检测之间的间隔通常是最具行动价值的数字。 以图中为例：故障于 14:03 开始，首次呼叫在 14:19 触发——存在 16 分钟的监测盲区。时间线之后紧接着用文字指出这一间隔：“检测比故障开始晚了 16 分钟；当时没有针对结账错误率的告警，只有主机 CPU 告警。”这句话通常会成为杠杆最高的改进项来源。
  • 条目应保持事实性并附有来源。分析应放在根因部分，而不是这里。

Step 6 — Trigger vs root cause vs symptom

步骤 6——区分触发因素、根因与症状

Give the reader the three definitions, then separate them cleanly. Conflating them is the most common way a postmortem produces a shallow fix.
  • Symptom — what was observed. "Checkout requests returned 500s; the pool showed zero free connections." The symptom is real but it is not the cause; fixing the symptom (restart, scale up) ends the incident without preventing the next one.
  • Trigger — the specific thing that set it off. "Config change #4821 halved the pool size at peak traffic." The trigger is necessary to the story but rarely the whole cause.
  • Root cause — the condition that made the trigger sufficient to cause the outage. Not "a bad config was pushed" — ask what made a bad config pushable to production at peak with no guard. The root cause is usually a missing safeguard, not the triggering action.
Push past the first plausible cause. If your answer is "someone pushed a bad config," you have named the trigger and stopped. Keep going: What allowed an unreviewed config to reach production? Why was there no validation on pool-size bounds? Why did no canary catch it? Techniques like "five whys" help you keep asking — but they are a prompt, not a proof, and they tend to walk you down a single chain when reality had several. Most incidents have several contributing factors and one or two root causes, not a single linear chain. Name the one or two conditions that, if they had not held, the trigger would have been harmless.
先向读者说明三者的定义，再清晰地将它们分开。将它们混为一谈，是 postmortem 导致浅层修复的最常见方式。
  • 症状（Symptom）——观察到的现象。“结账请求返回 500；连接池显示可用连接数为零。”症状是真实存在的，但它不是原因；只修复症状（重启、扩容）可以结束事故，却无法防止下一次事故。
  • 触发因素（Trigger）——直接引发事故的具体事项。“配置变更 #4821 在流量高峰期将池大小减半。”触发因素是事故叙事所必需的部分，但很少是完整原因。
  • 根因（Root cause）——让触发因素足以引发故障的条件。不要止步于“有人推送了错误配置”——要追问是什么让错误配置能够在高峰期未经审查地进入生产环境。根因通常是一个缺失的安全防护，而不是触发行为本身。
不要停留在第一个看似合理的原因。 如果答案只是“有人推送了错误配置”，那么你找到的只是触发因素。继续追问：是什么让未经审查的配置得以进入生产环境？为什么没有对池大小边界进行校验？为什么没有 canary 捕获它？five whys 等技术有助于持续追问——但它只是提示，而不是证据，而且往往会把你带入单一因果链，而现实通常由多个因素共同作用。大多数事故有多个促成因素，以及一两个根因，而不是一条线性因果链。请指出一两个条件：如果这些条件不成立，触发因素本会无害。

Step 7 — Contributing factors

步骤 7——促成因素

The conditions that widened the blast radius, delayed detection, or slowed recovery. These are not the root cause but they are why the incident was as bad as it was — and each is usually its own action item.
Look specifically for:
  • Missing or misrouted alerts — the detection gap from Step 5 almost always lands here.
  • Absent or stale runbook — no documented recovery path, so the on-call improvised. Check 
    guides/
    and its 
    last_verified
    dates.
  • Unclear ownership — nobody knew who owned the failing component, so acknowledgement lagged.
  • A stale guide — a runbook that said to do the thing that made it worse, or whose 
    last_verified
    was long past.
  • Compounding conditions — peak traffic, a concurrent deploy freeze, a second on-call already paged.
List each as a discrete factor. Vague "communication could have been better" is not a factor; "there was no owner mapping for the payments pool, so the first page went to the wrong team for 7 minutes" is.
这些条件扩大了爆炸半径、延迟了检测，或拖慢了恢复。它们不是根因，却解释了事故为何如此严重——每项通常都应对应一个独立改进项。
具体检查：
  • 告警缺失或路由错误——步骤 5 中的检测缺口几乎总会落在这里。
  • runbook 缺失或过期——没有记录成文的恢复路径，导致值班人员临场即兴处理。检查 
    guides/
    及其 
    last_verified
    日期。
  • 责任归属不清晰——没人知道故障组件由谁负责，因此确认响应被延迟。
  • guide 过期——其中的 runbook 要求执行的操作反而让情况变得更糟，或其 
    last_verified
    已经过期很久。
  • 条件叠加——流量高峰、同时处于发布冻结期，或已有另一名值班人员被呼叫。
将每项作为独立因素列出。笼统地说“沟通本可以更好”不算因素；“payments 连接池没有负责人映射，因此首次呼叫在 7 分钟内被错误转交给其他团队”才算。

Step 8 — What went well (genuinely)

步骤 8——做得好的事项

This section is not filler and skipping it quietly is a failure mode. Something limited the damage; name it so the org preserves it.
  • What made detection or recovery faster than it could have been? A good dashboard, a fast rollback path, a clear escalation.
  • What held up under load? The circuit breaker that shed load cleanly, the read replica that absorbed traffic.
  • Which prior action item paid off here? If a previous postmortem's fix limited this incident, say so and link it — that is the strongest possible argument for funding action items.
Write it honestly. If genuinely little went well, say that plainly rather than manufacturing praise — "recovery was slow and manual; the one thing that worked was that rollback was a single command." Preserving what worked is as much the point as fixing what didn't.
这一节不是填充内容；悄悄跳过它就是一种失效模式。某项措施限制了损害范围；应明确指出，使组织得以保留这一做法。
  • 什么让检测或恢复比本可能的速度更快？优秀的 dashboard、快速的回滚路径、清晰的升级机制。
  • 什么在负载下保持稳定？干净地卸载负载的 circuit breaker、吸收流量的只读副本。
  • 哪项过去的改进项在本次事故中发挥了作用？如果之前 postmortem 的修复限制了本次影响，请说明并附链接——这是为改进项争取资源的最佳论据。
如实书写。如果确实几乎没有事情做得好，就直说，不要生硬地制造赞扬——“恢复过程缓慢且依赖人工操作；唯一奏效的是，回滚只需执行一条命令。”保留有效做法与修复无效做法同样重要。

Step 9 — Action items: owned, dated, verifiable

步骤 9——改进项：有负责人、有截止日期、可验证

An action item with no owner is a wish. Every item gets three things or it does not go in the list:
  • An owner — a role or team (blameless: "the payments team," not a person's name unless the person self-assigns).
  • A due date — a real date, not "soon."
  • A verifiable done-condition — something you could check and unambiguously call done. "Add an alert on checkout error rate >2% for 3 minutes, tested by triggering it in staging" — not "improve alerting."
Classify each item by what it buys you:
  • Prevention — stops this exact recurrence (add pool-size validation to the config pipeline).
  • Mitigation — limits the damage next time it happens anyway (auto-shed load when the pool saturates).
  • Detection — finds it sooner (the missing error-rate alert from Step 5).
A healthy postmortem has items across all three; a list that is all prevention often means the detection and mitigation gaps went unexamined.
Guide-shaped action items produce runbook stubs. When an item is "write/fix the recovery runbook for X," don't just name it — stub it now:
write({ document: { path: "guides/db-pool-exhaustion-runbook.md", template: "runbook" } })
Pre-fill the stub with the symptom (how you'd recognize this again — "checkout 500s + pool free-connections at zero") and the relevant timeline excerpt (the rollback steps that actually worked, lifted from Step 5). Then link the stub from the action item: 
- [ ] Payments team, by 2024-03-16: complete the [pool-exhaustion runbook](./guides/db-pool-exhaustion-runbook.md), verified by a tabletop dry-run.
The runbook carries 
last_verified
frontmatter so it surfaces in review when it goes stale.
没有负责人的改进项只是愿望。每项都必须具备以下三项条件，否则不要列入清单：
  • 负责人——一个角色或团队（无责原则：“payments 团队”，而不是个人姓名，除非该本人主动认领）。
  • 截止日期——一个真实日期，而不是“尽快”。
  • 可验证的完成条件——能够检查并明确判定完成的事情。“添加结账错误率超过 2% 且持续 3 分钟的告警，并通过在 staging 中触发来验证”——而不是“改进告警”。
按每项能带来什么进行分类：
  • 预防（Prevention）——阻止此类问题再次发生，例如为配置流水线增加池大小校验。
  • 缓解（Mitigation）——即使问题再次发生，也能限制损害，例如连接池饱和时自动卸载负载。
  • 检测（Detection）——更早发现问题，例如补上步骤 5 中缺失的错误率告警。
一份健康的 postmortem 应涵盖这三类；如果清单全是预防项，通常意味着检测和缓解缺口未被认真审视。
以 guide 形式呈现的改进项会生成 runbook 存根。 当某项是“编写/修复 X 的恢复 runbook”时，不要只写下来——立即创建存根：
write({ document: { path: "guides/db-pool-exhaustion-runbook.md", template: "runbook" } })
使用症状（如何再次识别它——“结账 500 + 池可用连接数为零”）和相关时间线摘录（步骤 5 中实际奏效的回滚步骤）预填存根。然后从改进项链接到该存根：
  • payments 团队，在 2024-03-16 前：完成 pool-exhaustion runbook，并通过桌面演练验证。
runbook 带有 
last_verified
frontmatter，因此过期时会在评审中浮现。

Step 10 — Link and validate

步骤 10——建立链接并验证

  • Add a 
    ## Related
    section linking every prior postmortem that shares a subsystem (from Step 2), plus the 
    decisions/
    and 
    specs/
    implicated — the decision that set the config policy, the spec for the component that failed. 
    [2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)
    , 
    [connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md)
    .
  • Link the runbook stubs you created in Step 9 from their action items (done above) and from 
    ## Related
    .
  • Update the hub of any folder you touched if it has one (an 
    INDEX.md
    in 
    postmortems/
    ) so the new incident shows up in the index — the preview becomes a live progress bar.
  • Validate: 
    audit({ path: "postmortems/YYYY-MM-DD-name.md" })
    returns clean (every lint violation + broken internal link) — fix every finding. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
  • 添加 
    ## Related
    （相关文档）章节，链接每一个共享同一子系统的历史 postmortem（来自步骤 2），以及事故涉及的 
    decisions/
    和 
    specs/
    ——即制定配置策略的决策、故障组件的 spec。例如 
    [2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)
    、
    [连接池大小决策](./decisions/2023-11-04-pool-sizing.md)
    。
  • 从改进项（已在上面完成）和 
    ## Related
    中链接步骤 9 创建的 runbook 存根。
  • 如果所触及的任何目录存在 hub，例如 
    postmortems/
    中的 
    INDEX.md
    ，则更新该 hub，让新事故出现在索引中——preview 就会成为实时进度条。
  • 验证：
    audit({ path: "postmortems/YYYY-MM-DD-name.md" })
    返回 clean（即不存在任何 lint 违规或损坏的内部链接）——修复每项发现。确认 frontmatter 完整，且摘要（Summary）/ 时间线（Timeline）/ 根因（Root cause）/ 做得好的事项（What went well）/ 改进项（Action items）各部分均已填写，没有遗留模板占位符。

Step 11 — Recap

步骤 11——回顾

Close in conversation with four things, tightly:
  1. Impact in one line, user-visible terms.
  2. Root cause in one sentence (the condition, not the trigger).
  3. The single highest-leverage action item — usually the one that closes the detection gap or the missing safeguard.
  4. Whether this is a repeat class — and if so, why the prior fix didn't hold.
Then point at the file: 
postmortems/YYYY-MM-DD-name.md
and any runbook stubs created.
在对话中简洁总结四件事：
  1. 用一行说明影响，采用用户可感知的表述。
  2. 用一句话说明根因，聚焦条件而非触发因素。
  3. 指出杠杆最高的单一改进项——通常是填补检测缺口或补上缺失安全防护的改进项。
  4. 说明这是否属于重复问题类别；如果属于，解释之前的修复为何未能奏效。
然后指出文件 
postmortems/YYYY-MM-DD-name.md
以及已创建的 runbook 存根。

Non-goals

非目标

  • Don't assign blame to people. Systems and roles, never individuals. If a name is load-bearing to the story, the story is framed wrong — find the system affordance instead.
  • Don't stop at the first plausible cause. "A bad config was pushed" is a trigger. Keep asking what made the trigger sufficient until you reach a missing safeguard.
  • Don't write action items you cannot verify. No owner, no date, no checkable done-condition means it is a wish, not an action item. Leave it out or fix it.
  • Don't quietly omit "what went well." Skipping it loses the practices worth preserving. If little went well, say so honestly rather than dropping the section.
  • Don't use a postmortem to relitigate a design decision. A postmortem documents what happened and what to change operationally. Arguing that the architecture should have been different belongs in a proposal (
    /frame-a-proposal
    ) or a design review (
    /review-a-design
    ) — link to it from Related; don't fight it here.
  • Don't fabricate the timeline. No entry without a source you can point at; reconstructed-from-memory entries are labelled inline as such.
  • 不要把责任归咎于个人。 写系统和角色，绝不写个人。如果某个姓名对叙事不可或缺，说明叙事框架本身有问题——应转而找出系统条件。
  • 不要停留在第一个看似合理的原因。 “有人推送了错误配置”只是触发因素。持续追问是什么让触发因素足以引发事故，直到找到缺失的安全防护。
  • 不要写入无法验证的改进项。 没有负责人、截止日期和可检查的完成条件，就只是愿望，不是改进项。将其省略或补全。
  • 不要悄悄省略“做得好的事项”。 跳过这一节会丢失值得保留的做法。如果确实没有什么做得好的，就如实说明，而不是删除这一节。
  • 不要使用 postmortem 重新争论设计决策。 postmortem 记录已经发生的事情以及需要在运营层面改变什么。主张架构本应不同，属于 proposal（
    /frame-a-proposal
    ）或 design review（
    /review-a-design
    ）的范围——可从 Related 中链接，但不要在这里争论。
  • 不要编造时间线。 任何条目都必须有可指明的来源；根据记忆重建的条目必须明确标注。