Diagnose

難しいバグに対応するための体系的なアプローチです。正当な理由がない限りフェーズをスキップしないでください。

コードベースを探索する際は、プロジェクトのドメイン用語集を使用して関連モジュールの明確なメンタルモデルを構築し、対象エリアのADRを確認してください。

フェーズ1 — フィードバックループの構築

**これがこのスキルの本質です。**他はすべて機械的な作業です。バグに対する高速で確定的なエージェント実行可能なパス/フェイルシグナルがあれば、原因を特定できます。二分探索、仮説検証、計装はすべてこのシグナルを活用するだけです。シグナルがなければ、コードを見つめるだけでは解決できません。

ここに不釣り合いな時間をかけてください。積極的に。創意工夫を凝らして。諦めないでください。

ループの構築方法 — おおよそこの順序で試してください

1. 失敗するテスト — バグに到達するあらゆる接点で（ユニット、統合、e2e）。
2. Curl / HTTPスクリプト — 実行中の開発サーバーに対して。
3. CLIの実行 — フィクスチャ入力を使用し、stdout を既知の正常なスナップショットと比較。
4. ヘッドレスブラウザスクリプト （Playwright / Puppeteer）— UIを駆動し、DOM/コンソール/ネットワークをアサート。
5. キャプチャされたトレースを再生。 実際のネットワークリクエスト / ペイロード / イベントログをディスクに保存し、分離したコードパスを通じて再生。
6. 使い捨てハーネス。 システムの最小限のサブセット（1つのサービス、モック化された依存関係）を起動し、単一の関数呼び出しでバグコードパスを実行。
7. プロパティ / ファズループ。 バグが「出力が時々間違う」場合、1000個のランダム入力を実行して失敗モードを探す。
8. 二分探索ハーネス。 バグが2つの既知の状態（コミット、データセット、バージョン）の間で発生した場合、「状態Xで起動、チェック、繰り返し」を自動化して git bisect run で実行できるようにする。
9. 差分ループ。 同じ入力を旧バージョンと新バージョン（または2つの設定）で実行し、出力を比較。
10. HITL bashスクリプト。 最後の手段。人間がクリックする必要がある場合、 scripts/hitl-loop.template.sh で彼らを駆動してループを構造化したままにする。キャプチャされた出力があなたにフィードバックされます。

正しいフィードバックループを構築すれば、バグは90%解決したも同然です。

ループ自体を反復改善する

ループを製品として扱ってください。_ある_ループを手に入れたら、以下を問い直してください：

• もっと速くできないか？（セットアップをキャッシュ、関連のない初期化をスキップ、テスト範囲を絞る）
• シグナルをもっと鮮明にできないか？（「クラッシュしなかった」ではなく、具体的な症状をアサート）
• もっと確定的にできないか？（時刻をピン止め、RNGをシード、ファイルシステムを分離、ネットワークを固定）

30秒のフレーキーなループは、ループがないのとほぼ同じです。2秒の確定的なループはデバッグの超能力です。

非確定的なバグ

目標はきれいな再現ではなく、より高い再現率です。トリガーを100回ループ、並列化、ストレスを加え、タイミング窓を絞る、スリープを挿入。50%のフレークバグはデバッグ可能です。1%はできません。デバッグ可能になるまで再現率を上げ続けてください。

ループを構築できない場合

明確に立ち止まってそう言ってください。試したことを列挙してください。ユーザーに以下を要求してください：(a) 再現環境へのアクセス、(b) キャプチャされた成果物（HARファイル、ログダンプ、コアダンプ、タイムスタンプ付きスクリーン記録）、または(c) 一時的な本番環境計装を追加する許可。ループなしで仮説段階に進まないでください。

フェーズ2に進む前に、信頼できるループがあることを確認してください。

フェーズ2 — 再現

ループを実行してください。バグが現れるのを観察してください。

確認してください：

• ループがユーザーが説明した失敗モードを出現させる — 近所で発生する別の失敗ではなく。間違ったバグ = 間違った修正。
• 失敗が複数回実行で再現可能である（または、非確定的なバグの場合、デバッグ可能なほど十分な高い率で再現可能）。
• 後のフェーズで修正が実際に対処することを検証できるように、正確な症状（エラーメッセージ、不正な出力、遅い処理時間）をキャプチャしている。

バグを再現するまで進まないでください。

フェーズ3 — 仮説を立てる

任意をテストする前に3～5個のランク付けされた仮説を生成してください。単一の仮説生成は最初のもっともらしいアイデアに固定化します。

各仮説は偽証可能でなければなりません。それが立てる予測を述べてください。

フォーマット：「<X>が原因であれば、<Y>を変更するとバグは消える / <Z>を変更するとより悪化する。」

予測を述べることができなければ、その仮説は根拠なき印象です。破棄するか鮮明にしてください。

テストする前にランク付けされたリストをユーザーに見せてください。 ユーザーはドメイン知識を持っており、すぐにランク付けを変更できます（「ちょうど#3に変更をデプロイした」）、または既に除外した仮説を知っているかもしれません。安価なチェックポイント、大きな時間節約です。ユーザーがAFKの場合はブロックしないでください — あなたのランク付けで進めてください。

フェーズ4 — 計装

各プローブはフェーズ3の特定の予測にマップ必要があります。一度に1つの変数だけ変更してください。

ツール優先度：

1. デバッガ / REPL検査 — 環境がサポートしていれば。1つのブレークポイントは10個のログに勝ります。
2. 対象ログ — 仮説を区別する境界で。
3. 「すべてをログに記録して grep する」は決してしない。

すべてのデバッグログに一意のプレフィックスでタグを付ける、例：[DEBUG-a4f2]。クリーンアップは最後に単一の grep になります。タグ付きされていないログは残り、タグ付きされたログは消えます。

Perfブランチ。 パフォーマンス低下の場合、ログは通常間違っています。代わりに：ベースライン測定（タイミングハーネス、 performance.now()、プロファイラ、クエリプラン）を確立し、二分探索します。測定してから修正します。

フェーズ5 — 修正 + リグレッション テスト

修正前にリグレッションテストを書いてください — ただし、正しいシームがある場合のみです。

正しいシームとは、テストが呼び出しサイトで発生する実際のバグパターンを実行するシームです。唯一利用可能なシームがあまりに浅い場合（複数の呼び出し側が必要な時の単一呼び出し側テスト、バグをトリガーしたチェーンをレプリケートできないユニットテスト）、そこでのリグレッションテストは誤った自信を与えます。

正しいシームが存在しない場合、それ自体が知見です。 それに注記してください。コードベースアーキテクチャがバグをロックダウンすることを妨げています。次のフェーズのためこれにフラグを立ててください。

正しいシームが存在する場合：

1. 最小化されたリプロをそのシーム失敗するテストに変える。
2. 失敗するのを見る。
3. 修正を適用。
4. 合格するのを見る。
5. 元の（最小化されていない）シナリオに対してフェーズ1フィードバックループを再実行。

フェーズ6 — クリーンアップ + ポストモーテム

完了を宣言する前に必須：

• 元のリプロはもはや再現されない（フェーズ1ループを再実行）
• リグレッションテストは合格（またはシーム不在が文書化されている）
• すべての [DEBUG-...] 計装が削除される（プレフィックスで grep）
• 使い捨てプロトタイプが削除される（または明確にマークされたデバッグ場所に移動）
• 正しいと判明した仮説がコミット / PRメッセージに記載される — 次のデバッガが学習できるように

そして問い直してください：このバグを何が防いだのか？ 答えがアーキテクチャ変更を含む場合（テストシーム不足、呼び出し元が絡み合う、隠れた結合）、具体を添えて /improve-codebase-architecture スキルに引き継いでください。修正の前ではなく、修正が入った後に推奨してください — 開始時より情報が多くあります。