fault-diagnosis

障害診断

概要

修正を推測すると時間を無駄にし、新たな不具合を招きます。応急処置では根本的な問題が隠れてしまいます。

基本原則： 修正を試みる前に、必ず根本原因を特定してください。症状への対処は失敗です。

例外なし。回避策なし。近道なし。

最優先の指示

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

フェーズ 1 を完了していない場合、修正を提案する権限はありません。

使用する場面

あらゆる技術的な問題に適用します。

• テストの失敗
• 本番環境のバグ
• 予期しない動作
• パフォーマンスの低下
• ビルドの失敗
• 統合の不具合

特に重要な場面：

• 時間に追われているとき（焦ると推測に頼りたくなります）
• 「ちょっとした修正」で解決できそうに見えるとき
• すでに複数の修正を試したとき
• 前回の修正で問題が解決しなかったとき
• 問題を十分に理解していないとき

省略してはいけない場面：

• 問題が単純に見えるとき（単純なバグにも根本原因があります）
• 急いでいるとき（体系的な調査のほうが、手当たり次第に試すより速く進みます）
• 誰かが「今すぐ」解決するよう求めているとき（手順を踏んだ作業のほうが、試行錯誤するより速く進みます）

4 つのフェーズ

次のフェーズに進む前に、各フェーズを必ず完了してください。

フェーズ 1：根本原因の調査

修正を試みる前に：

1. エラーメッセージを詳しく読む

   • エラーや警告を読み飛ばさないでください
   • 多くの場合、そこに正確な答えが含まれています
   • スタックトレースを最後まで読みます
   • 行番号、ファイルパス、エラーコードを記録します

2. 確実に再現する

   • 一貫して発生させられますか？
   • 正確な再現手順は何ですか？
   • 毎回発生しますか？
   • 再現できない場合は、推測せずにデータをさらに集めます

3. 最近の変更を調べる

   • 何が変わり、それが原因になり得ますか？
   • Git の差分、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

4. 複数コンポーネントから成るシステムでは証拠を集める

   システムに複数のコンポーネント（CI -> ビルド -> 署名、API -> サービス -> データベース）がある場合：

   修正を提案する前に、診断用の計測を追加します：

   For EACH component boundary:
     - Log what data enters the component
     - Log what data exits the component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to collect evidence showing WHERE it breaks
   THEN analyze evidence to identify the failing component
   THEN investigate that specific component
   

   例（多層システム）：

   # Layer 1: Orchestrator
   echo "=== Orchestrator state: ==="
   echo "TOKEN: ${TOKEN:+SET}${TOKEN:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Build environment: ==="
   env | grep TOKEN || echo "TOKEN not in environment"
   
   # Layer 3: Signing module
   echo "=== Certificate state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual operation
   codesign --sign "$IDENTITY" --verbose=4 "$ARTIFACT"
   

   これにより判明すること： どのレイヤーで失敗しているか（シークレット -> オーケストレーターは OK、オーケストレーター -> ビルドは失敗）

5. データフローをたどる

   コールスタックの深い位置でエラーが発生している場合：

   完全な逆方向トレースの方法については、このディレクトリの root-cause-tracing.md を参照してください。

   要約：

   • 不正な値はどこから来ていますか？
   • どの処理が、この関数を不正な値で呼び出しましたか？
   • 発生源が見つかるまで上流へたどります
   • 症状ではなく、発生源を修正します

フェーズ 2：パターン分析

修正する前にパターンを見つけます：

1. 正常に動作する例を探す

   • 同じコードベース内で、似たような正常動作するコードを探します
   • 問題のあるコードに似ていて、正常に動作するものは何ですか？

2. 参照例と比較する

   • パターンを実装する場合は、参照実装を最後まで完全に読みます
   • ざっと読まず、すべての行を読みます
   • 適用する前にパターンを完全に理解します

3. 違いを特定する

   • 正常に動作するものと問題のあるものの違いは何ですか？
   • どんなに小さな違いでもすべて書き出します
   • 「影響するはずがない」と決めつけないでください

4. 依存関係を理解する

   • ほかにどのコンポーネントが必要ですか？
   • 必要な設定、構成、環境は何ですか？
   • どのような前提がありますか？

フェーズ 3：仮説とテスト

科学的手法：

1. 仮説を 1 つ立てる

   • 「Y であるため、X が根本原因だと考えます」と明確に述べます
   • 書き留めます
   • 曖昧にせず、具体的にします

2. 最小限のテストを行う

   • 仮説を検証するために、可能な限り最小限の変更を加えます
   • 一度に変更する変数は 1 つだけにします
   • 複数のことを同時に修正しないでください

3. 続行する前に検証する

   • 解決しましたか？ はい -> フェーズ 4
   • 解決しませんでしたか？ 新しい仮説を立てます
   • 追加の修正を次々と重ねないでください

4. わからないとき

   • 「X を理解できていません」と伝えます
   • 知っているふりをしないでください
   • 助けを求めます
   • さらに調査します

フェーズ 4：実装

症状ではなく、根本原因を修正します。

1. 失敗するテストケースを作成する

   • 可能な限りシンプルに再現する
   • 可能であれば自動テストにする
   • テストフレームワークが利用できない場合は、単発のテストスクリプトを作成する
   • 修正に着手する前に必ず用意する
   • 適切な失敗テストの作成には godmode:test-first スキルを使用する

2. 修正を1つだけ実装する

   • 特定した根本原因に対処する
   • 一度に変更するのは1つだけ
   • 「ついでに」改善しない
   • リファクタリングをまとめて行わない

3. 修正を検証する

   • テストは合格するか
   • ほかのテストに影響はないか
   • 問題は実際に解決したか

4. 修正がうまくいかない場合

   • 停止する
   • 修正を何回試したか数える
   • 3回未満の場合：フェーズ 1 に戻り、新たな情報をもとに再分析する
   • 3回以上の場合：停止し、アーキテクチャを見直す（下記の手順 5）
   • アーキテクチャについて議論する前に、4回目の修正を試みてはいけません

5. 修正に3回以上失敗した場合：アーキテクチャを見直す

   アーキテクチャに問題があることを示すパターン：

   • 修正のたびに、別の場所で新たな共有状態、密結合、問題が見つかる
   • 修正の実装に「大規模なリファクタリング」が必要になる
   • 修正するたびに、別の場所で新たな症状が発生する

   停止して、根本的な点を見直す：

   • このパターンは根本的に妥当か
   • 惰性だけで続けていないか
   • 症状の修正を続けるのではなく、アーキテクチャをリファクタリングすべきではないか

   さらに修正を試みる前に、人間のパートナーと話し合ってください

   これは仮説の失敗ではなく、アーキテクチャの欠陥です。

ガードレール — 停止して手順に従う

次のように考えていることに気づいたら：

• 「とりあえず応急処置をして、調査は後で」
• 「Xを変えて、どうなるか試してみよう」
• 「複数の変更を適用してからテストしよう」
• 「テストは省略して、手動で確認しよう」
• 「おそらくXだろう。修正してみよう」
• 「完全には理解できていないが、うまくいくかもしれない」
• 「パターンではXとなっているが、別の方法にしよう」
• 「主な問題は次のとおりです：[調査せずに修正を列挙する]」
• データフローを追跡する前に解決策を提案している
• 「もう一度だけ修正を試す」（すでに2回以上試している場合）
• 修正のたびに、別の場所で新たな問題が見つかる

これらはすべて、停止してフェーズ 1 に戻るべきサインです。

修正に3回以上失敗した場合： アーキテクチャを見直してください（フェーズ 4、手順 5 を参照）。

人間のパートナーが示す、軌道から外れているサイン

次のような方向修正に注意してください：

• 「それは実際に起きているのですか？」— 確認せずに思い込んでいます
• 「それで分かるのでしょうか？」— 証拠を集める仕組みを追加すべきでした
• 「当てずっぽうはやめて」— 理解しないまま修正を提案しています
• 「もっと深く考えて」— 症状だけでなく、根本的な点を見直してください
• 「行き詰まっていますか？」（苛立った様子）— そのアプローチはうまくいっていません

このようなサインに気づいたら： 停止してフェーズ 1 に戻ってください。

認知の落とし穴

自分を正当化する考え	実際のところ
「問題は単純だから、手順は不要だ」	単純な問題にも根本原因はあります。この手順なら、単純なバグはすばやく解決できます。
「緊急事態で、手順を踏む時間がない」	体系的な診断は、当てずっぽうで試行錯誤するより速く済みます。
「まずこれを試してから調査しよう」	最初の修正が、その後の進め方の基準になります。最初から正しく進めてください。
「修正がうまくいくと分かったら、テストを書こう」	テストされていない修正は維持できません。先にテストを書けば、修正を検証できます。
「一度に複数の修正をすれば時間を節約できる」	何が有効だったかを特定できず、新たなバグを生みます。
「参照資料が長すぎるので、パターンを応用しよう」	理解が不十分だと、必ずバグにつながります。最後まで読んでください。
「問題は分かった。修正しよう」	症状が見えていることと、根本原因を理解していることは同じではありません。
「もう一度だけ修正を試す」（2回以上失敗した後）	3回以上の失敗は、アーキテクチャの問題を示しています。同じパターンを見直し、再度修正しないでください。

クイックリファレンス

フェーズ	主な作業	成功基準
1. 根本原因	エラーを読み、再現し、変更を確認して、証拠を集めます	何が起きているのか、なぜ起きているのかを理解する
2. パターン	動作する例を見つけて比較します	違いを特定する
3. 仮説	仮説を立て、最小限のテストを行います	仮説を確認するか、新しい仮説を立てる
4. 実装	テストを作成し、修正して、検証します	バグが解決し、テストに合格する

調査で根本原因が見つからない場合

体系的に調査して、問題が本当に環境依存、タイミング依存、または外部要因によるものだとわかった場合：

1. 調査プロセスは完了しています
2. 調査した内容を記録します
3. 適切な対処（再試行、タイムアウト、エラーメッセージ）を実装します
4. 今後の調査に備えて、監視とログ記録を追加します

ただし：「根本原因が見つからない」ケースの95%は、調査が不十分です。

補助的な手法

これらの手法は障害診断の一部であり、このディレクトリから利用できます：

• root-cause-tracing.md - コールスタックをさかのぼってバグを追跡し、最初の引き金を見つけます
• defense-in-depth.md - 根本原因の特定後、複数のレイヤーに検証を追加します
• condition-based-waiting.md - 任意のタイムアウトを条件ポーリングに置き換えます

関連スキル：

• godmode:test-first - 失敗するテストケースの作成に使用します（フェーズ4、ステップ1）
• godmode:completion-gate - 成功を宣言する前に、修正が機能したことを検証します

実際の効果

診断セッションから：

• 体系的なアプローチ：解決まで15～30分
• 場当たり的な修正：2～3時間にわたる試行錯誤
• 初回の修正成功率：95% 対 40%
• 新たに発生するバグ：ほぼゼロ 対 よく発生