writing-postmortems

ポストモーテムの書き方

必須の前提知識: technical-writing スキル（ハードルール、真実のルール、スタイル）。

概要

想定読者は、1年後に同じような問題に遭遇するエンジニアであり、その場にいる人たちではありません。中心となる原則は、証拠から事実を、メカニズムから原因を、その両方から教訓を導き、固有名詞は書かないことです。分類は歴史的記録であり、一度レビューされれば不変で、訂正は日付付きの追記とします。

いつ呼び出すか、呼び出さないか

インシデントが解決した後、または長期にわたるインシデントの安定したマイルストーンで呼び出します。ユーザーに到達した欠陥とヒヤリハット（レバレッジのレビューが見逃したものをガードが捉えた事例）は、同じ書き方が求められます。インシデントの発生中には呼び出さないでください。その状況はランブックが統制します。責任の割り当てのために書くものではありません。人の名前がないと意味が通らないポストモーテムは、プロセスの穴を説明していることになります。ステークホルダーへのステータス更新のために書くものでもありません。それはレポートです。

骨子

# [System]: [the failure, as its symptom, one line]

| | |
|---|---|
| **Incident date** | YYYY-MM-DD |
| **Duration** | detection to resolution |
| **Severity** | [per the org taxonomy, defined where used] |
| **Status** | Draft / Reviewed |

## Summary
[User-visible impact with numbers, the root cause in one sentence, current state.
The reader who stops here still knows what happened.]

## Impact
[Who and what, quantified: requests failed, records affected, money or time lost.
Estimates labeled as estimates; "no evidence of data loss" only if actually checked,
and say what was checked.]

## Timeline
[Timestamped entries, facts only, each traceable to evidence: an alert, a log line,
a commit, a message. Interpretation lives in the sections below, never here.]

## Root cause and contributing factors
[The mechanism, grounded in code and commits. Contributing factors as a list;
"every component was correct and the defect lived between them" is a valid root
cause. Name which layer of checking missed it and which caught it.]

## Wrong turns during the response
[The wrong first fix, the misleading signal followed, the theory that cost an hour.]

## Action items
[Each with an owner and an acceptance check, filed as tracker issues and linked.
"Investigate X" without an owner is banned here as everywhere.]

## Sign-off
[- YYYY-MM-DD <reviewer>: approved <scope>, one line per review event.]

ルール

• 非難しないとは構造を指すということです。 役割、ゲート、依存関係、欠けているガードを名指しし、決して個人を名指ししません。個人を非難しても「もっと注意する」で終わりますが、構造を非難すればアクションアイテムが生まれます。これはナラティブ（タイムライン、原因、対応）を統制します。アクションアイテムのオーナーシップは割り当てであり、非難ではありません。この文書では役割、リンクされたトラッカーの issue では個人です。
• タイムラインは証拠であり、ナラティブではありません。 すべてのエントリは検証可能なものに遡り、タイムスタンプは記憶ではなくシステムから取得します。記憶が唯一の情報源である場合は、その旨を明記します。
• 間違った修正も内容です。 もっともらしく思えたが機能しなかった修正は、それがもっともらしく思えた理由とともに文書に含めるべきです。気まずさは保存ポリシーではありません。
• 重大度は組織のタクソノミーから導きます。 使用する場所で定義され、前提とはしません。タクソノミーが存在しない場合は、勝手に作らず、そのフィールドを明示的に未割り当てのままにします。
• アクションアイテムは writing-issues に従います。 成果、担当者、受け入れチェック、起票とリンクを行い、ポストモーテム内の文章による意図として残しません。あなたの立場から起票できない場合は、各アイテムに [to file: <who files it>] と記し、リンクが存在するまでポストモーテムは Draft のままにとどめます。
• 一度レビューされたら不変です。 新たな発見は日付付きの追記であり、書き直されたポストモーテムは改ざんされた記録です。レビュー自体は署名行に記します（コアスキルの references/truth.md を参照）。
• ヒヤリハットも同じ骨子を使います。 Impact には起こり得たことを記述し、それが反事実であることを明示します。

ポストモーテムの後によく続く決定（新しい不変条件、ポリシー変更）は、recording-decisions を通じて記録し、リンクします。埋め込みはしません。インシデントが明らかにしたランブックの更新は、修正と同じチェンジで writing-runbooks を通じて行います。ドキュメント化は完了の一部であり、フォローアップチケットではありません。