root-cause

根本原因

観測された障害と後続の症状を説明する、最小の因果メカニズムまたは十分な因果要因の集合を見つけます。診断は、トリアージ／レビュー／修正の提供とは分離して行います。

実質的な分析、調査、専門家による作業はサブエージェントに委任し、メインコンテキストを簡潔に保てるよう、調査結果と証拠リンクを簡潔にまとめて返します。

有用なモデルの例：

trigger + enabling conditions + propagation + missing containment/detection → observed failure

障害を特定する

症状、期待される動作、最初に確認されたトリガー、候補／リビジョンまたはイベントの識別情報、環境／コンテキスト、再現性、証拠、範囲、読み取り／調査の権限を正確に記録します。報告、スタックトレース、相関関係、変更された成果物、時間的な前後関係は証拠であり、原因ではありません。

可能であれば安全に再現し、そうでなければ同等の直接観測を1つ特定します。一次障害と、二次エラー、再試行、補償動作、復旧時のノイズを分けて扱います。

競合するメカニズム

簡潔な仮説表を作成します。各仮説について、トリガー／メカニズム、成立条件、伝播、説明できる証拠、仮説を区別できる観測事項、安全性を保てる最小限の調査を記載します。

仮説を区別できる、範囲を限定したソース／履歴／Git の証拠がある場合は、調査コマンドを確認します。対象分野に適した既存の観測、テスト、ログ、トレース、設定、履歴、測定結果、可逆的な診断を優先します。

次の観測や介入は、定番のデバッグ手順だからではなく、現在の仮説を区別できるかどうかに基づいて選択します。可能な範囲で、重要な交絡要因を制御します。1つの要因だけを変える調査は、その方法でメカニズムを実際に区別できる場合に限って行います。相互作用や結合した条件が疑われる場合は、それらの相互作用を明らかにできる観測／調査を設計し、要因が独立しているかのように扱うことは避けます。

提案する因果説明について、次の点を確立します。

1. 説明の十分性 — 提案されたメカニズム／要因の集合が、未解決の因果的な空白を残さず、観測された障害と重要な後続症状を説明または再現できること。
2. 要因の裏付け — 主張する各因果要因について、関連するコンテキストでの寄与を示す、仮説を区別できる証拠があること。可能であれば、要因を取り除く／制御することで、期待されるとおりに結果または予測された媒介要因が変化すること。
3. 条件性と代替経路 — 別の十分な経路、相互作用、またはコンテキストでも同じ障害が発生しうる場合、ある要因を全体的に必要条件とみなさないこと。その要因が、今回観測された経路に必要なのか、寄与しているのか、成立を可能にしているのか、相互作用しているのか、未解決なのかを明記します。

仮説を区別できる裏付けのない要因は、障害より前に発生したというだけで確認済みの根本原因とみなさず、コンテキスト要因／寄与要因／未解決要因として扱います。

証拠に基づいて停止する

安全な追加観測によって因果モデルを実質的に更新できる間だけ続けます。残る仮説を区別できない場合、安全な調査で診断を変えられない場合、必要な環境／可観測性／権限が得られない場合、または障害を再現できず同等の直接証拠も存在しない場合は停止します。

Root Cause の作業中に修正を試みてはいけません。

結果

次のいずれか1つを返します。

• CONFIRMED_ROOT_CAUSE — 最小の因果メカニズム／要因の集合と、仮説を区別する証拠が、観測された障害／経路に対して十分である。
• DIAGNOSED_BUT_UNPROVED — 最有力の説明に、重要な因果的／証拠上の空白がある。
• EVIDENCE_BLOCKED — 証拠／環境／権限／可観測性の不足を明示する。
• NOT_REPRODUCED — 特定した障害を観測できず、同等の直接証拠もない。

障害の識別情報、最小限のメカニズム／要因の集合、要因ごとの証拠と因果上の役割、重要な相互作用／別の十分な経路、寄与要因／コンテキスト要因／未解決要因、伝播／封じ込め、決定的な証拠、否定された代替仮説、影響を受ける境界、確信度の限界、次に実行すべき最小限の有用なアクションを含めます。

必要な診断は、既存のプロジェクト内の保存先に永続化します。選択した共有ワークスペースには akosile を使用し、必要に応じて html-artifact を使用します。