diagnose-issue

問題を診断する

動作を変更する前に、証拠に基づいて原因を特定します。ユーザーが修正または実装を明示的に依頼していない限り、診断は読み取り専用です。

外部ドキュメントやツールの動作が関係する場合は、research-ladder.md を使用してください。リポジトリに用語集や ADR がある場合は、それらを参照してください。

プロセス

1. 最も役立つフィードバックループを最短で構築します。対象を絞ったテスト、ビルド、CLI 呼び出し、リクエスト、ブラウザーでの確認、トレースの再生、ベンチマーク、小規模な使い捨てハーネスなどを使用します。
2. 可能であれば報告された症状を再現し、正確な失敗内容を記録します。動作が不安定な場合は、再現率のベースラインを記録し、変更との比較に十分な頻度まで再現率を上げます。再現できない場合は、結論と仮説を区別し、重要な不足証拠のみを求めます。
3. 必要に応じて、エラー、ログ、スタックトレース、最近の差分、依存関係や設定の変更、環境の違い、呼び出し元、近隣の正常な使用例をすべて確認します。
4. 不確実性が残る間だけ、反証可能な仮説を優先順位付きで維持します。直接的な証拠で原因が説明できる場合は、別の仮説を作り出さずに検証へ進みます。
5. もっともらしい原因を切り分けられる境界に計測を追加します。入力、手順、設定、呼び出し元を一つずつ取り除いて再現可能な症状を最小化し、不可欠な要素だけを残します。不正な値の発生源を追跡し、パフォーマンスを測定し、任意の待機時間ではなく実際の非同期条件を待ちます。
6. 最も有力な原因と、意味のある代替原因を支持または除外する証拠を示します。

修正が許可されている場合

• 有効な接点がある場合は、修正前に失敗する回帰テストを優先します。
• 原因に対処する最小限の変更を適用します。
• 公開契約、移行、永続化、認証／セキュリティ動作、本番環境の状態、またはパフォーマンス上のトレードオフについてオーナーの判断が必要な場合は、変更を加えずに停止し、選択肢を提示します。
• 変更を繰り返しても解決しない場合は、パッチを積み重ねずに停止します。新たな証拠を踏まえて、メンタルモデル、フィードバックループ、アーキテクチャを再評価します。
• 元のフィードバックループと関連する回帰チェックを再実行し、成功を主張する前に結果を確認します。
• 提出前に、review-work を通じて独立した新しいコンテキストのレビュアーに、最新のパッチだけでなく作業全体の範囲をレビューしてもらいます。承認された主張を一次証拠で検証し、許可されたブロッキング指摘を修正して、影響を受けるチェックを再実行します。
• この作業で作成した一時的な計測機能とスクラッチ成果物のみを削除します。既存の下書き、フィクスチャ、無関係な作業は保持します。

正しい修正に安全なテスト接点やアーキテクチャ上の接点がない場合は、その制約を報告し、未解決の設計を improve-architecture または plan-work に引き継ぎます。動作を変えないことが分かっている整理は、バグ修正に紛れ込ませず simplify-work に引き継ぎます。

出力

報告は簡潔にまとめます。

• 原因と証拠
• 修正（許可されている場合のみ）
• 実施した検証
• 制約、残存リスク、または推奨する次の対応

診断を実験の逐語録にせず、証拠が裏付ける範囲を超えて確実性を主張しないでください。