awesome-root-cause

根本原因分析

根本原因を突き止め、持続的な対策につなげます。対象は、再現できる失敗テストがないインシデント、繰り返し発生する障害、プロセス上の問題です。個人を責めないことを前提とし、目指すのは個人の責任追及ではなく、システム全体の改善です。

awesome-bug-fix および awesome-performance-audit との使い分け

• このスキル — 障害の振り返り、「何度も壊れる」という問題、データ品質や引き継ぎ、デプロイプロセスの問題、ニアミスに使います。失敗の原因がプロセス、環境、連携にあり、実行して失敗を確認するだけでは解決できない場合に適しています。
• awesome-bug-fix — 再現可能な、特定のコードバグに使います。失敗するテストを書けるなら、そのスキルを使ってください。実行できるものがない場合は、こちらを使います。
• awesome-performance-audit — 定期的に発生する場合も含め、サービスやページの速度低下、メモリリーク、レイテンシーの急上昇に使います。原因を尋ねる前に、まず測定します。

問題が複合的な場合（壊れたプロセスによってコードバグがリリースされた場合など）は、awesome-bug-fix でバグを修正し、このスキルでバグを招いたプロセスに対処します。

ワークフロー

1. 問題を定義する

解決策や責任者ではなく、観測可能なギャップとして問題を述べます。現状と期待される状態、発生時期、頻度、影響範囲、根拠（ログ、チケット、タイムラインなど）を示します。ギャップを具体的に述べられない場合は、分析の前にさらに情報を集めてください。

記憶ではなく、記録（ログ、チケット、デプロイ履歴、チャット）からタイムラインを作成し、発生、検知、緩和、解決の4つを個別に記録します。検知までの時間（発生から検知まで）は、それ自体が重要な発見です。シグナルには遅延があります。アラームは評価ウィンドウの後に鳴り、メトリクスのデータポイントは集計期間の一端（多くの場合は開始時点）に記録され、イベント発生時刻には記録されません。ログのフラッシュが遅れたり、監査イベントが操作の後に届いたりすることもあります。そのため、発生時刻はアラームが鳴った時刻ではなく、生データに見られる最も早い異常です。記録では説明できないタイムラインの空白は、推測で埋めずにチームに確認します。

影響範囲は、環境またはアカウント、リージョン、サービス、操作、リソースの順に、上位から絞り込みます。同じ階層の複数のユニットが同時に影響を受けている場合は、そのうちの一つを掘り下げる前に、それらが共有している依存関係（ネットワーク、DNS、ID、共有パイプラインなど）を調べます。

2. 候補を広げる（フィッシュボーン）

掘り下げる前に、6つの原因カテゴリ（人、プロセス、テクノロジー、環境、手法、資材）を確認し、明白な原因に固執しないようにします。それぞれのカテゴリに候補となる要因を列挙します。根本原因はテクノロジーよりもプロセスや手法にあることが多く、技術だけが原因となるケースは例外であり、標準ではありません。

3. 実際の候補をそれぞれ掘り下げます（5 Whys）

残った候補ごとに、「なぜ」を連鎖的に問いかけます。ルールは2つです。

• 人ではなく、システム上の欠陥にたどり着いたら止めます。連鎖が「人的ミス」で終わる場合は、「なぜそのミスが起き得たのか？」とさらに掘り下げます。真の根本原因は、検証の欠如、自動化の欠如、または不明確な手順です。人を変えるだけでは解決できない原因こそ、見つける価値があります。
• 回数に決まりはありません。その問題の「種類」を防げる原因にたどり着いたら止めます。3回でも7回でも構いません。5回に合わせて水増しする必要はありません。

各連鎖の結論は、単なる主張ではなく、証拠に裏付けられた根本原因候補にします。

調査の並列化（候補が多数ある場合）。魚骨図を使った洗い出し（ステップ2）と5 Whysの連鎖（ステップ3）は、独立した読み取り専用の証拠調査です。原因カテゴリごと、または残った候補ごとにサブエージェントを1つ割り当て、それぞれがログ、チケット、タイムラインを収集するようにします。ステップ4で合流します。親エージェントが、同じシステム上の欠陥に収束した連鎖を重複排除し、「1つの事例ではなく、1つの種類」のテストを適用し、対策候補全体の優先順位を決めます。各連鎖を担当するエージェントは候補を提案しますが、最終的な対策は作成しません。リソースの事前確認（分散前）：1回の実行で起動するサブエージェントは数個に抑えます。各エージェントがブラウザー、言語サーバー、またはテストを実行する場合は、さらに少なくします。CPUやメモリがすでに不足している場合は逐次実行します。実行環境がサブエージェントの同時実行数を制限している場合は、その制限に従います。

4. 対策（まずはポカヨケ）

確認された根本原因ごとに、「もっと注意する」よりも、再発を構造的に困難にする予防策を優先します。

• 注意喚起よりも、不適切な状態を不可能にする仕組み（ガード、必須フィールド、CIでのチェックなど）を設けます。
• 失敗した手作業のステップを自動化します。
• 曖昧な手順を明確にするか、削除します。 影響度 × 実現可能性 ÷ 工数で対策の優先順位を決めます。それぞれに担当者を割り当てます。

5. PDCAで検証します

各対策を完了事項ではなく、実験として扱います。

• Plan — 変更前に、定量化可能な成功基準を定めます（「4週間、再発ゼロ」「引き継ぎエラーを週3件から0件に削減」など）。
• Do — 対策を1つ実施します。
• Check — 基準に照らして測定します。自己申告ではなく、サーバー側または独立した指標を使います。
• Act — 継続、調整、または元に戻す判断をします。 3サイクル実施しても変化がなければ、根本原因が間違っています。ステップ3に戻ってください。

出力：1ページの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

報告書の読みやすさ

ポストモーテムは、その場にいなかった人や、1年後に次のオンコールを担当する人が読みます。文書には、タイムゾーン付きの絶対時刻、正確な障害の仕組み、行き詰まった試行錯誤、担当者が明確なアクションアイテムが記されています。チームのインシデント用テンプレートを使うのは問題ありません。見分けるポイントは、その中身が水増しされているかどうかです。文章のルール（awesome-humanize-en/references/domain-postmortems.md に見分け方をまとめた表があります。このスキルがない場合は、以下のルールがすべてです）：

• 誰も責めないことと、実行主体を曖昧にすることは別です。「ミスがありました」「変更がデプロイされました」と、主体をまったく示さない表現は曖昧です。システムや役割を明記してください。「デプロイパイプラインが、検証の実行前に設定を昇格させました」のように書きます。
• タイムラインには、誤った判断や試行も残します。誤った仮説に費やした40分間は、文書の中で最も多くを学べる部分であり、報告書から最も頻繁に省かれる部分でもあります。絶対時刻を記し、タイムゾーンは一度明記します。
• コードや設定レベルでの仕組みを記します。正確なクエリ、フラグ、上限値、競合が発生する時間枠などです。まだ誰も把握していないなら、それはチームが検討すべき問いであり、文章で取り繕うために空欄にしてよいものではありません。
• アクションアイテムは、担当者と期限が決まった変更です。「監視とコミュニケーションを改善する」はアクションアイテムではありません。「キューの深さが10kを超えたときのアラートを追加する（担当：infra、期限：09-15）」のようにします。
• 自画自賛する副詞は使いません。「チームは迅速に特定しました……」と書かなくても、タイムスタンプが速さの判断材料になります。タイムスタンプに語らせてください。
• 妥当だと考える因果関係を明示し、本当に不明な部分は不明と記します。「複数の要因が影響した可能性があります」は、判断を示すべきところでの逃げです。
• まず影響を数値で示し（継続時間、失敗したリクエスト数、影響を受けたユーザー数、判明していれば損失額）、その後に説明を加えます。数値はインシデントのデータに基づくものであり、きりのよい数に見せるために丸めてはいけません。
• テンプレートの各セクションは、記載する長さに見合う内容が必要です。「うまくいったこと」に何もなければ、率直な一文にするか削除します。体裁を整えるための段落を書く必要はありません。
• アクションアイテムで終えます。信頼性を重視する文化について、教訓めいた結論を加えてはいけません。また、誤った判断を一つも認めていないポストモーテムは、まだ書き上がっていません。

ガードレール

• 非難しないこと。個人ではなく、システムや手順を明記します。「デプロイにステージング環境の承認ゲートがありませんでした」とし、「Xがテストせずにデプロイしました」とは書きません。
• 説明より証拠を優先します。根本原因には、その根拠となるもの（ログの1行、チケット、タイムラインの項目など）を必ず示します。もっともらしい説明も、証拠に裏付けられるまでは仮説です。
• 根拠がなければ結論を出しません。根本原因の特定に必要なタイムラインやデータが不足している場合は、不足しているものを記し、原因候補の段階で止めます。報告書を締めくくるために、整った根本原因をでっち上げてはいけません。
• 個別の事象ではなく、問題の分類全体を対象にします。今回の事象だけを修正し、同じ分類の問題には対処しない対策は不完全です。そのことを明記してください。

例 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?