rca-report

RCA レポート

単なる経緯の説明ではなく、再現可能で、多層的で、運用に役立つポストモーテムを作成します。優れた RCA があれば、将来のエンジニア（あるいは未来の自分）がインシデントを理解し、修正が維持されていることを検証し、再発を防げます。このスキルでは、調査の流れ（インシデントの記憶が新しいうちに収集する情報）とレポート自体の両方を扱います。

このスキルを適用する場面

• 本番環境のインシデント、障害、またはニアミスが発生し、記録が必要な場合
• パイプライン、サービス、またはシステムが気づかないうちに失敗し、ユーザーが直前に解決した場合
• ユーザーがポストモーテム、RCA、またはインシデント報告書を求めている場合
• 調査の途中で、ユーザーが何かをデバッグしており、得られた証拠を整理する支援を求めている場合

インシデントが現在進行形で深刻化していて、ユーザーが解決の支援だけを求めている場合は、このスキルを使わず、まず修正してください。記録はその後に行います。

出力先

レポートは、現在の作業ディレクトリに <topic>-rca-<YYYY-MM-DD>.md として保存します。ここで：

• <topic> は、障害が発生したシステムを表す短いケバブケースの識別子です（例：debezium、auth-service、kafka-consumer-lag）
• <YYYY-MM-DD> はインシデント発生日です。必ずしも今日とは限りません

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

2 段階のワークフロー

フェーズ 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 タイムスタンプ付きのタイムラインがある — 「コネクターが約18時間停止していた」は説明にすぎません。「2026-05-04 09:54:16 に Postgres がレプリケーション接続を終了した」は証拠です。常に、より正確な表現を優先してください。

2. システムを完全に特定できるインフラストラクチャの表がある — バージョン、ホスト名、ゾーン、コネクター名、トピック名、スロット名などを記載します。6か月後に読む人でも、曖昧さなく正確なリソースを見つけられるようにしてください。

3. ユーザー、システム、データ、SLA の各側面で影響を定量化している — 曖昧な影響（「一部の顧客が影響を受けた」など）は、重大度の判断には役立ちません。ユーザーに見える影響、内部システムの劣化、データの整合性の状態、SLA／金銭的コストを具体的な数値で示してください。数値が不明な場合は、その側面を省略せず、明示的に不明と記載してください。

4. 階層化された根本原因分析がある — 単に何が壊れたかだけでなく、次の点も明らかにします。

   • 主因（引き金となったイベント）
   • 正常に見えていた理由（障害を覆い隠したもの。通常、ここが最も有益な情報です）
   • 二次的な要因（ゲート、再試行、影響を与えた内部状態）

5. 実際の値を含む状態のスナップショットがある — 期待された状態と観測された状態の対比によって、診断の要点が明確になります。confirmed_flush_lsn = 1/AD5B16C0 (pre-restore stale value) と pg_current_wal_lsn = 1/ADC4B740 (current) を並べれば、2行で全体像がわかります。対象の領域に応じて、同様の対比を記録してください（キューの深さ、エラー率、バージョンの不一致、スキーマのドリフトなど）。

6. 回避策／一時的な緩和策を、解決策とは分けて記録している — 根本原因を完全に把握する前に、被害の拡大を止めるために実施した、迅速でリスクの低い対応です。回避策と解決策では答える問いが異なります。回避策は、次に同じ事象が発生したとき、午前3時にオンコール担当者が何をするかです。解決策は、事案を恒久的に終結させる方法です。回避策の効果とリスク、適用する条件を記録してください。

7. 手順の順序に理由を添えた解決策がある — 単に「これらのコマンドを実行した」ではなく、なぜこの順序なのかを記します。インメモリ状態のために手順4を手順3の後に実行する必要があるなら、その理由を説明してください。次に同じ問題に直面する人は、まず直感的な順序で試して失敗するでしょう。直感的な順序ではうまくいかない理由を記録してください。

8. システム上の欠落に行き着く「なぜなぜ分析」 — 分析は、技術的な引き金ではなく、欠けている防護策（アラート／レビュー／テスト／ナレッジ）に行き着いて初めて有用になります。「なぜ」を重ねるたびに、異なるメカニズムへと絞り込んでください。隣り合う段階で同義語を繰り返すのは、内容を水増ししているだけです。最後の回答は、その下に記載する推奨事項に直接対応している必要があります。

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 — [理由]」と記載します。
6. 品質基準（references/quality-rubric.md）に照らして検証します。基準を満たさない点があれば、提示する前に修正します。
7. CWD に <topic>-rca-<YYYY-MM-DD>.md として保存します。
8. ファイルパスをユーザーに伝え、必要に応じて各セクションを一緒に確認すると申し出ます。 求められない限り、報告書全体をチャットに貼り付けないでください。ユーザーはファイルを読みます。

トーン

運用担当者の文体に合わせます。技術的で簡潔、証拠に基づいた記述にします。各セクションでは、まず結論を述べ、その後に理由を説明します。「何らかの影響があった可能性があります」のような企業的な曖昧表現は避け、何が起きたのかを明確に述べます。誰かを責めず、個人ではなくシステム上の不備に焦点を当てます。参考資料の Debezium RCA のように、率直に書きます。