diagnose

diagnose — 根本原因の切り分け

運用上の不変条件

• 調査範囲：本番ソースと既存テストを読みます。一時的なハーネス、フィクスチャ、トレースの再生データ、レポートファイルは .agents/scratch/ 内にのみ作成します。根本原因のレポートを作成した時点で終了し、本番環境への修正、恒久的なテスト、修正用の変更セットは後続の作業に委ねます。
• 作業ツリーの保全：既存の変更とスクラッチ成果物を保全します。プローブは分離したコピーか、既存の読み取り専用の接続箇所に対して実行し、計測コードを本番ソースに含めないでください。一時的なプローブには [DEBUG-<hex>] のタグを付け、証拠を収集した後は、このセッションで作成した計測コードのみを削除します。
• 機密性の高い証拠と環境：ログに記録する前にシークレットをマスキングします。シークレットファイル（.env*、*.key、*.pem）は決して調べないでください。実行環境は .agents/dev-environment.md に基づいて準備し、実行範囲をローカルのスクラッチ領域内に厳密に限定して、本番環境やホストレベルのコンテナーには触れないでください。

ドメイン別の指針

受付と因果関係の証拠

• 不具合の説明、エラー、ログ、スタックトレース、または再現手順を受け付けます。期待される動作、観測された動作、関連する環境、実行上の接続箇所を特定し、証拠の欠如と矛盾する証拠を区別します。
• 実行可能な RED が用意できない場合でも、利用可能な証拠に基づいて調査を開始します。失敗するアサーションは症状の証拠として扱い、原因は、判別力のあるプローブ、決定的な実行トレース、または検証済みの因果関係を通じて特定します。
• トリガーや状況と、失敗を引き起こすメカニズムを分けて考えます。根拠を示せる仮説ごとに、予測を明記します：If <cause>, then <controlled probe> changes <observation>.
• 証拠が得られる場合は、競合する説明も検証します。一度に変える因果要因は1つにし、候補ごとに各結果が支持するか反証するかを記録します。明白な構文エラーや決定論的な失敗については、不要なハーネスを作るより直接トレースを優先します。

再現とフィードバックループ

症状と利用可能なランタイムに忠実な、最小のループを選びます：

接続箇所	調査方法
既存テスト	失敗する呼び出し箇所で、対象を絞ったアサーションを実行します
実行中のプロセス	CLI または HTTP 経路を呼び出し、期待値と実際の出力を比較します
分離された呼び出し可能な処理	最小限のスクラッチハーネスを作成し、置き換えた I/O を明示します
キャプチャ済みイベント	サニタイズ済みのペイロード、ログ、または HAR データをスクラッチ領域で再生します
過去のリグレッション	分離したスクラッチチェックアウトでリビジョンを比較します
対話操作でのみ発生するトリガー	ローカルループのテンプレート をスクラッチ領域で調整して使い、マスキング済みの応答を記録します

• 症状を正確に維持しながら、入力、設定、手順を最小限にします。関連する統合動作を含め、忠実性の確保に必要な要因はすべて保持します。
• 間欠的な失敗では、可能な範囲でシード、時計、イベント順序、または並行処理を制御します。試行回数、失敗、介入の結果を報告し、運よく1回成功しただけで証明とみなすことなく、回数を限定して繰り返します。
• 実際のアーキテクチャ上の接続箇所を保持します。モックが疑わしいメカニズムを省略している場合、または忠実な接続箇所がない場合は、その証明上の不足を記録し、範囲内で証拠に基づく調査を続けます。

結論の状態

• CONFIRMED：因果メカニズムと、そのメカニズムが報告された症状につながる関係の両方が証拠で検証されています。
• INFERRED：証拠は具体的な因果仮説を支持していますが、明記された不足があるため確認には至っていません。
• REJECTED：判別力のある証拠が、明示した範囲で調査対象の因果関係を反証しています。不具合そのものが否定されたかのように示唆せず、どの主張が反証されたかを特定します。
• UNRESOLVED：利用可能な証拠では根拠を示せる原因が得られないか、入力、環境、アクセス上の制約によって意味のある結論に至れません。

標準出力の要件

簡潔なレポートを1つ作成します。推論を再現または検証するのに十分なコマンド、関連する観察結果、ソースの場所を記載します。必要に応じて、未加工のログはサニタイズ済みのスクラッチ成果物に保存します。

# Root-Cause Report: <defect>

State: <CONFIRMED | INFERRED | REJECTED | UNRESOLVED>
Conclusion: <causal mechanism, supported hypothesis, rejected claim, or unresolved question>
Scope: <symptom, runtime/environment, and inspected seam>
Evidence: <commands or trace references; observed results; discriminating causal link>
Conditions and proof limits: <assumptions, substitutions, missing evidence, and applicability limits>

## Competing explanations *(omit if none were investigated)*
<claim -> probe/prediction -> observation -> supported or falsified>

## Reproduction *(omit if no executable or interactive loop was established)*
<scratch path or existing command; required setup; assertion and observed symptom>

ルーティング

• 既存の候補と方向性について解決策の証明が必要な場合 → （/spike 経由）。
• 根本原因の調査結果に解決策の方向性が必要な場合 → （/architect-decision 経由）。

実行プロトコル

1. 提供された証拠に基づいて症状を把握し、関連する呼び出しチェーンを調査します。絞り込んだ因果関係の疑問と、利用可能な検証ポイントを記録します。
2. 可能であれば、忠実な RED ループを確立し、最小化します。実行できない場合は、トレースとソースの証拠を調べ、欠けている証明を記録しながら続行します。
3. 原因が確認されるか、明示的な不足事項を伴って裏付けられるか、反証されるか、未解決となるまで、優先順位を付けた仮説を検証します。以降の検証に利用できない入力やアクセスが必要となる場合、または同じ兆候を繰り返し確認するだけの場合は、その調査分岐を終了します。
4. 状態と証明の限界を示して根本原因のレポートを提示します。有用なサニタイズ済みの再現用成果物を保持し、セッション固有の計測機能を削除して、本番ファイルに変更がないことを確認します。