diagnose

診断

明示的な diagnose または diagnose-fix-loop の呼び出し後に、このワークフローを使用します。通常のバグ報告や修正依頼では、このワークフローの実施は求められていません。

判別力のある証拠を使って、依頼された症状の原因を特定し、説明します。実用的な調査によって結論が変わる可能性がある間は、より強い証拠を探します。信頼でき、範囲が限定された修正を行う前に、数値による信頼度のしきい値を満たす必要はありません。

ユーザーが示した具体的な手掛かり（ファイル、ルート、エラー、ログ、画面、ブランチ、成果物、再現手順）を起点にします。関連するアーキテクチャのメモ、ADR、用語集、テストのドキュメントを参照します。コードを調査し、安全なツールやテストを実行して、既存の成果物を分析します。

Diagnose の明示的な呼び出しは、依頼された範囲内で、一時的な計測を動作に影響しない形で行うことへの承認とみなします。範囲を限定した修正には、会話内ですでに与えられている承認、または diagnose-fix-loop の呼び出しによる承認を再利用します。次のアクションにその承認がない場合、アクセス手段がない場合、または重大な判断が未解決の場合に限り、確認を求めます。

参照資料

該当するものだけを読み込みます。

• ブラウザーまたは React のウェブアプリ：browser-react.md
• iOS、Android、React Native、macOS、TV、または実機：app-device.md。macOS アプリのセッションでは、デフォルトで agent-device のネイティブバックエンドを使用します。アプリを開く前に、そのセットアップと XCTest のフォールバックを読んでください。
• ログ、実行時プローブ、メトリクス、またはデバッグフック：instrumentation.md

証拠収集ループ

1. 原因の候補を絞り込みます。 ユーザーが示した手掛かりに関連するコードパスと既存の証拠を調査します。役に立つ範囲で最小限の原因候補を挙げ、反証可能な形にします。該当する場合は、独立した原因や寄与する原因も含めます。それぞれの原因について、区別につながる予測を示し、予測がどこで異なるかを特定します。

2. 原因を判別できる証拠を選びます。 まず既存のテスト、トレース、ログを使います。それだけでは有力な原因候補を区別できない場合は、instrumentation.md を読み込み、関連する境界に一時的な構造化プローブを追加します。1 回の再現で区別できるよう、競合する原因を同時に計測します。

   再現する前に、プローブの仕様を定義します。

   • 正確なトリガーと目に見える症状
   • 今回の実行で答える質問
   • 原因候補ごとの、区別につながる予測
   • その予測を検証するイベント、フィールド、相関 ID
   • 証拠を正確な表示上の障害と結び付ける方法
   • 該当する場合、対象となるプロセス、ビルド、ウィンドウ、ドキュメント、実行環境の ID

   ベースラインの再現を行い、計測前に症状を確認してもかまいません。再現結果を因果関係の証拠として扱う前に、その観測結果で有力な原因候補を区別でき、正確な症状を確認できることを確かめます。

3. 問題を再現します。 報告された症状を表す最も高速で決定性の高いシグナルを使います。対象を絞ったテスト、スクリプト、ブラウザーテスト、トレースの再生、ハーネス、反復ループ、プロファイラー、アプリ／デバイスの自動化、または構造化された手動再現などです。安全で、観測可能であれば実行します。断続的に発生する問題は、原因を比較できるだけの回数を繰り返します。

   再現にアクセス不能な状態、認証情報、デバイス、主観的な操作、またはリスクのあるアクションが必要な場合は、まずキャプチャ方法、正確な手順、期待される観測結果、調査対象の成果物を準備します。そのうえでユーザーに再現を依頼し、done と返信してもらいます。返された証拠が報告された問題と一致することを確認します。

   ユーザーがトリガー、影響を受けるコンポーネント、ライフサイクル、または表示上の症状を訂正した場合、以前の解釈を対象にした証拠やプローブは無効にします。再現に進む前に、原因の特定と計測に戻ります。似ているものの一致しない再現を続けてはいけません。

4. 収集して分析します。 出力全体を収集し、境界をまたいでイベントを相関させ、それぞれの予測と比較して、すべての原因候補について支持する証拠と反証する証拠を記録します。ログが不完全または曖昧な場合は、次の再現に向けて原因候補の範囲や計測方法をどう変更すべきかを特定します。

5. 確信度を判断します。 各原因を役割（根本原因、寄与要因、代替原因）ごとに順位付けし、0-100% の確信度、裏付けとなる証拠と矛盾する証拠、スコアや順位を変える可能性のある次の証拠を示します。スコアは定性的な判断であり、較正済みの統計的確率として扱わないでください。次の条件をすべて満たす場合に限り、運用上の確信度を100%とします。

   • 正確な症状を再現できる
   • トリガーから障害に至る因果関係を確認できる
   • 疑わしい境界を制御すると、症状も確実に制御できる
   • 原因または原因の組み合わせで、関連するすべての観測結果を説明できる
   • もっともらしい代替原因が否定されているか、寄与要因として含まれている
   • 断続的な挙動を、因果関係と偶然を区別できるだけ十分に繰り返している

   証明が不完全な場合は、原因を識別する証拠が得られる可能性が高い、最も安全で実用的な調査方法を選び、どの結果が確信度を上げるのか、下げるのか、または振り分け直すのかを明記してください。そのような調査方法がある間に限り、可能性の高い領域や計測方法を見直して検証サイクルを繰り返します。入力、境界、または計測方法を変えずに、同等の検証を繰り返してはなりません。

   利用可能な調査方法で確信度が上がらない場合、ある検証で新たな証拠が得られず、かつ別の境界も残っていない場合、または必要な証拠を得るのに利用できないアクセス、ユーザーの操作、許容できないリスク、あるいは過度の労力が必要な場合は、調査を終了します。利用可能な証拠が信頼できる原因と範囲を限定した修正を裏付ける場合は「裏付けあり」と報告し、それ以外の場合は「未完了」と報告します。未解決の証明を、証明済みと表現してはなりません。

出力

最初に、次のいずれかのステータスを示してください。

• 証明済み — 100%： 該当するすべての原因が証明基準を満たし、未解決のもっともらしい代替原因がありません。
• 裏付けあり： 証拠から信頼できる原因と範囲を限定した修正が特定されており、具体的な不確実性が残っています。
• 未完了： 利用可能な証拠では、信頼できる原因や修正をまだ裏付けられません。

証明済みまたは裏付けありの場合は、原因、因果関係、決定的な証拠、コードまたはランタイムの境界、残る不確実性を報告してください。未完了の場合は候補を順位付けし、証拠が不十分な理由を説明したうえで、最小限で有用な次の調査方法を示してください。必ず検証シグナルを明記してください。確信度スコアは判断であり、測定された確率ではありません。

一時的な診断情報

ユーザーからクリーンアップを依頼されるか、永続的な診断情報になるまで、診断ログを保持してください。一時的な診断情報が残っている状態でコミットする場合は、永続化する変更だけをステージし、ステージされていないまま残るものを報告してください。

委任

ユーザーが委任、サブエージェント、並列作業、またはトークン最適化を明示的に依頼した場合に限り、サブエージェントを使用してください。既知のコマンドや再現ループ、ログ、スクリーンショット、トレース、プロファイル、抽出、成果物の比較など、範囲を限定できる機械的な収集作業は、より高速または低コストのエージェントに委任します。各タスクには、成功条件、出力形式、ランタイムの境界、変更が明示的に許可されていない場合の編集禁止指示を含めてください。

フィードバックループの設計、仮説の順位付け、確信度のスコアリング、曖昧な結果の解釈、最終診断は、メインスレッドで行ってください。委任した証拠を検証し、続行する前に作業ツリーとバックグラウンドプロセスを確認してください。