---
name: postmortem-writer
description: |
  インシデント発生後のポストモーテム（事後分析）ドキュメントを作成するスキル。
  Google SRE のベストプラクティスに基づいた Blameless Postmortem を日本語で執筆する。
  以下のようなフレーズが出たときは必ずこのスキルを使うこと:
  - 「ポストモーテムを書いて」「ポストモーテムにまとめて」「ポストモーテムを作成して」
  - 「障害報告書を書いて」「インシデントレポートを作成して」
  - 「事後分析をドキュメントに」「障害の振り返りをまとめて」
  - 「postmortem」「post-mortem」「incident report」「RCA」への言及
  - 障害・インシデント・ダウンタイム・サービス停止後に「まとめて」「振り返りを」
  過去の障害だけでなく、ヒヤリハット（near-miss）のポストモーテム作成にも対応すること。
---

# Postmortem Writer スキル

インシデント発生後に、Google SRE のベストプラクティスに準拠した
Blameless Postmortem ドキュメントを日本語で作成するスキル。

---

## 基本原則

このスキルで作成するポストモーテムは、以下の原則に従う。
これらは Google SRE が提唱する Blameless Postmortem の核心であり、
個々のステップよりも重要な指針として常に意識すること。

1. **Blameless（非難しない）** — 個人の過失ではなくシステムの改善機会に焦点を当てる。
   「Xさんが間違えた」ではなく「システムがXさんの誤操作を防げなかった」と記述する。

2. **正直さと透明性** — 都合の悪い事実も含めて正確に記録する。
   不都合な真実を隠すと、同じ問題が再発する。

3. **アクション駆動** — 全てのアクションアイテムに担当者と期限を設定する。
   担当者・期限のないアクションアイテムは実行されない。

4. **定量的** — 可能な限り影響を数値で表現する。
   「多くのユーザーが影響を受けた」ではなく「推定X,XXXユーザーに影響」と記述する。

5. **学習の共有** — ポストモーテムはチーム・組織の学習資産である。
   他のチームが同種の問題を予防できるよう、知見を共有可能な形で記録する。

---

## ステップ 1: テンプレートと既存ポストモーテムの確認

```bash
# テンプレートを読む（このスキルにバンドルされたテンプレートを使用）
cat <skill-directory>/template.md

# プロジェクト内に既存のポストモーテムディレクトリがあるか確認
find . -type d -name "postmortems" -o -name "post-mortems" -o -name "incidents" 2>/dev/null | head -5

# 既存のポストモーテムがあれば最新のものを確認（フォーマットの踏襲のため）
ls docs/postmortems/ 2>/dev/null | sort | tail -3
```

- プロジェクト固有のポストモーテムディレクトリやテンプレートがあればそちらを優先する。
- 既存のポストモーテムがあればフォーマットや命名規則を踏襲する。
- どちらもなければ、バンドルされた `template.md` を使う。
- ポストモーテムの保存先が不明な場合はユーザーに確認する。

---

## ステップ 2: インシデント情報の収集

ポストモーテムの品質は収集する情報の質に依存する。
以下のソースから可能な限り情報を集める。

### 2a. 会話から得られる情報

ユーザーとの会話から以下を抽出する:
- 何が起きたか（症状）
- いつ起きたか（タイムライン）
- 影響範囲（ユーザー数、サービス、機能）
- 原因の仮説または確定した原因
- 実施した対応策

### 2b. システムから収集可能な情報

会話内容を補完するために、プロジェクトのコードベースやログから情報を収集する。

```bash
# 直近のコミット履歴（障害の原因となった変更を特定）
git log --oneline --since="YYYY-MM-DD" --until="YYYY-MM-DD" | head -20

# 直近の変更差分（障害に関連する変更を確認）
git diff <commit-before>..<commit-after> --stat

# Docker コンテナの状態（マイクロサービスの場合）
docker compose ps 2>/dev/null
docker compose logs --tail=100 <service-name> 2>/dev/null

# アプリケーションログ（ログファイルがある場合）
tail -200 logs/application.log 2>/dev/null
```

### 2c. 情報が不足している場合

以下の情報が会話やシステムから得られない場合は、ユーザーに質問する。
ただし一度に大量の質問をせず、最も重要な3つ以内に絞ること。

**必須情報（これがないとポストモーテムが成立しない）:**
- インシデントの概要（何が起きたか）
- タイムライン（いつ検知し、いつ復旧したか）
- 根本原因（判明している場合）

**あると品質が上がる情報:**
- 影響の定量データ（ユーザー数、エラー率、レイテンシ等）
- 検知の経緯（アラート？ユーザー報告？）
- 対応の経緯（誰が何をしたか）

---

## ステップ 3: ポストモーテムの執筆

### 執筆ルール

1. **テンプレートの構成に従う** — 各セクションを網羅的に記述する
2. **日本語で書く** — コード・コマンド・サービス名・技術用語は英語のまま
3. **Blameless を徹底する** — 人名ではなくロール名（「オンコール担当者」等）を使う
4. **機微な情報を含めない:**
   - 本番環境のIPアドレス・ドメイン・ポート番号の具体値
   - 認証情報・APIキー・シークレット
   - 顧客の個人情報・企業名（影響範囲の説明に必要な場合は匿名化する）
5. **定量的に書く** — 「多くの」「少しの」ではなく具体的な数値を使う
6. **Five Whys を丁寧に行う** — 表面的な原因で止めず、システム的な根本原因まで掘り下げる

### セクション別の執筆ガイド

**サマリー:**
何が・いつ・どの程度の時間・どの程度の影響で発生したかを3〜5文で。
技術的な詳細はここに書かず、後続セクションに委ねる。

**影響:**
可能な限り定量的に。「エラー率がX%に上昇」「レイテンシがp95でXmsからYmsに劣化」
「推定X,XXXリクエストが失敗」のように具体的な数値を用いる。

**タイムライン:**
全時刻をJSTで統一する。検知・対応開始・原因特定・緩和・復旧の5つは必須。
各イベントは事実のみを簡潔に記述し、判断の評価は「対応の評価」セクションで行う。

**根本原因分析:**
Five Whys は最低3段階、理想的には5段階まで掘り下げる。
「人為的ミス」で止めず、「なぜそのミスが起きやすいシステムだったか」まで分析する。
寄与要因（contributing factors）も見逃さず記録する。

**アクションアイテム:**
以下の4カテゴリに分類する:
- **予防（Prevent）:** 再発防止策。コード修正、設計変更、自動化等
- **検知（Detect）:** 早期発見策。アラート追加、モニタリング改善等
- **緩和（Mitigate）:** 影響最小化策。フェイルオーバー、サーキットブレーカー等
- **プロセス（Process）:** 対応プロセス改善。ランブック整備、訓練等

全てのアクションアイテムに **担当者** と **期限** を設定すること。
「いつかやる」は実行されない。

---

## ステップ 4: ファイルに書き込む

```bash
# ポストモーテムのファイル名は以下の規則に従う
# PM-YYYY-NNN-<短い説明>.md
# 例: PM-2026-001-feed-registration-timeout.md

# 保存先の決定（既存ディレクトリがあればそちら、なければ作成）
mkdir -p docs/postmortems

# ファイルに書き込み（Git管理されているためバックアップ不要）
cat > docs/postmortems/<filename>.md << 'POSTMORTEM_EOF'
<執筆した内容>
POSTMORTEM_EOF

# 書き込み確認
cat docs/postmortems/<filename>.md
```

保存先はプロジェクトの規約に従う。一般的な候補:
- `docs/postmortems/`
- `docs/incidents/`
- `postmortems/`
- ユーザーが指定した任意のパス

---

## ステップ 5: 品質チェック

執筆後、以下のチェックリストで品質を確認する。

### 必須チェック

- [ ] サマリーが3〜5文で簡潔にまとまっているか
- [ ] タイムラインに検知・対応開始・原因特定・緩和・復旧の5イベントが含まれるか
- [ ] 根本原因分析が「人為的ミス」で止まらず、システム的な原因まで掘り下げられているか
- [ ] 全てのアクションアイテムに担当者と期限が設定されているか
- [ ] Blameless の原則に反する表現（個人名での非難等）がないか
- [ ] 機微な情報（本番IP、APIキー、顧客情報等）が含まれていないか

### 推奨チェック

- [ ] 影響が定量的に記述されているか
- [ ] 検知方法と TTD（Time to Detect）が記録されているか
- [ ] 「うまくいったこと」「運が良かったこと」も記録されているか
- [ ] 教訓セクションに技術的/組織的な学びが記述されているか
- [ ] 関連するADR・Issue・PRへのリンクが含まれているか

---

## ステップ 6: 完了報告

以下をユーザーに報告する:

1. 書き込んだポストモーテムファイルのパス
2. インシデントの重大度と影響時間のサマリー
3. 特定された根本原因の要約（1〜2文）
4. アクションアイテムの件数と内訳（予防X件、検知X件、緩和X件、プロセスX件）
5. `git diff` で変更差分を表示（オプション）

---

## 重大度の基準（参考）

ユーザーが重大度を指定しない場合、以下を参考に提案する。

| 重大度 | 基準 |
|--------|------|
| SEV-1 | サービス全面停止、データ損失、またはセキュリティ侵害 |
| SEV-2 | 主要機能の停止または重大なパフォーマンス劣化（多数のユーザーに影響） |
| SEV-3 | 一部機能の停止または軽度のパフォーマンス劣化（一部ユーザーに影響） |
| SEV-4 | 軽微な問題またはヒヤリハット（ユーザー影響なしまたは最小） |

---

## ヒヤリハット（Near-Miss）の場合

実際にはインシデントに至らなかったが、至る可能性があった事象の場合:

- 「影響」セクションには実際の影響（なし or 最小）と、**潜在的影響**を記述する
- タイムラインは検知と対応のみでよい（復旧は不要な場合が多い）
- 根本原因分析は通常のインシデントと同様に行う
- アクションアイテムは予防策を重点的に記述する
- 重大度は SEV-4 を基本とするが、潜在的な影響度に応じてユーザーと相談する

---

## 注意事項

- ポストモーテムは可能な限り48時間以内に作成する（情報の鮮度が重要）
- 長大なログやチャットログは要約し、原本は別途リンクする
- 1つのインシデントに1つのポストモーテム（複数インシデントを1つにまとめない）
- アクションアイテムの進捗管理は、GitHub Issues や Jira 等のタスク管理ツールで行うことを推奨する
- OSSプロジェクトのポストモーテムでは、セキュリティに関する詳細を公開前に慎重にレビューすること