Hunt: 修正する前に診断する

最初の行の前に 🥷 をインラインで付けます（段落としてではなく）。

症状に適用されたパッチは別の場所で新しいバグを生成します。

根本原因を 1 文で述べることができるまで、コードに触れてはいけません：

「根本原因は [X] だと考えます。理由は [証拠] です。」

具体的なファイル、関数、行、または条件を指定してください。「状態管理の問題」はテスト不可能です。「依存配列に userId が不足しているため、src/hooks/user.ts:42 の useUser のキャッシュが古い」はテスト可能です。これほど具体的に述べることができない場合、仮説がまだ不完全です。

診断シグナル

良い進捗：ログ行が仮説と一致している、次のエラーを実行前に予測できる、根本原因から症状への伝播経路を理解している、古いコードで失敗するテストを作成できる。これらのシグナルのそれぞれで、コミット前にさらに 1 つ独立した証拠を見つけてください。

仮説の品質ゲート：仮説に基づいて行動する前に、すべての観察可能な症状（ユーザーが最初に報告したものだけではなく）をリストアップしてください。仮説がすべての症状を説明する必要があります。一部のみカバーしている場合、それは根本原因ではなく症状レベルの推測です。タイミング依存の問題（ちらつき、断続的な失敗、競合状態）の場合、診断前に確実に再現してください。

合理化の警告：「試してみるだけ」は仮説がない、最初に書いてください。「自信がある」は実証する計器を実行することを意味します。「おそらく同じ問題」は実行経路をゼロから再度読むことを意味します。「私のマシンでは動く」は却下する前にすべての環境差分を列挙することを意味します。「もう一度再起動」は最後のエラーを逐語的に読むことを意味します。新しい証拠なしに 2 回以上再起動しないでください。

永続的なコンテキストプリフライト

これはユーザーがメモリ、プレビュー、以前の決定、または前の結論を言及するときだけ実行します。ユーザーがメモリパスを提供するときや、現在のプロジェクトが明らかなローカルメモリ概要を公開するときだけです。マシン固有のメモリルートをハードコードするか、生のトランスクリプトを読まないでください。

永続的なコンテキストをこの順序で読んでください：ユーザーが提供するパス、現在のプロジェクト範囲、その後グローバル設定。最初にタイトルをリストアップし、最大 1～2 個の関連する概要を開いてください。クロスプロジェクトエントリを移譲可能なパターンのみとして扱います。

メモリタイプをマッピングしてから使用します：decision、preference、principle は診断制約を説明します。pattern と learning は仮説に種を提供できます。fact は診断に影響を与える前に現在の状態に対して検証する必要があります。現在のコード、ログ、再現手順、テスト、環境バージョン、およびリモート状態はメモリをオーバーライドします。

/hunt の場合、永続的なコンテキストは仮説の燃料のみです。新しい根本原因文、再現可能な症状リスト、または現在の状態からの証拠を置き換えることはありません。

硬いルール

• 修正後の同じ症状は硬い停止です。「試してみるだけ」も同様です。 どちらも仮説が未完成であることを意味します。再度コードを触る前に実行経路をゼロから再度読んでください。
• 3 つの失敗した仮説の後、停止します。 以下のハンドオフ形式を使用して、何が確認されたか、何が除外されたか、何が不明かを明らかにしてください。どう進めるか尋ねてください。
• 確認してから主張します。 バージョン、関数名、またはファイルの場所をメモリから述べないでください。最初に sw_vers / node --version / grep を実行してください。結果がない = パスを再検討してください。
• 外部ツールの失敗：切り替える前に診断します。 MCP ツールまたは API が失敗するとき、最初に失敗した理由を判断します（サーバーが実行されていますか？API キーが有効ですか？設定が正しいですか？）。代替方法を試す前に。
• 偏向に注意を払います。 誰かが「その部分は重要ではない」と言うとき、それをシグナルとして扱います。誰かが検査を避ける領域は、問題が存在する場所です。
• ビジュアル/レンダリングバグ：静的分析を最初に。 DevTools でペイントレイヤー、スタッキングコンテキスト、レイヤーの順序をトレースしてから、console.log またはビジュアルデバッグオーバーレイを追加してください。ログはコンポジターが何をするかをキャプチャできません。静的分析が失敗した後のみインストルメンテーションを追加してください。
• 症状ではなく原因を修正します。 修正が 5 つ以上のファイルに触れる場合、一時停止してスコープをユーザーと確認してください。

二分探索モード

次の場合に有効にしてください：「以前は好的」、「之前是好的」、「used to work」、「上一次提交还是对的」、「broke after update」、またはユーザーが特定の良いコミットまたはバージョンを覚えているとき。

1. 候補となる良いタグを見つけます：git tag --sort=-version:refname | head -10 またはユーザーに最後の既知の良好なコミットを尋ねます。
2. 二分探索を開始する前に、インタラクティブでないパス/失敗テストコマンドを定義します。二分探索は再現可能なチェックなしではまったく役に立ちません。
3. 実行：git bisect start && git bisect bad HEAD && git bisect good <tag-or-hash>
4. 各ステップで二分探索がコミットをチェックアウトします。テストコマンドを実行してください。マーク：git bisect good または git bisect bad。
5. 二分探索に任せます。明示的に要求される場合を除き、先に進んだりコミットをスキップしたりしないでください。
6. 二分探索が犯人コミットを名付けるとき、そのdiffだけを読んでください。回帰を導入した特定の行を特定してください。
7. 完了したら git bisect reset を実行してください。

大きなファイルは 1 回読んで、二分探索の各ステップで再度読むのではなく、メモから参照します。

繰り返される回帰 / スクリーンショット参照モード

ユーザーが修正後に同じ問題が依然として間違っていると言う、「良い」スクリーンショット/バージョン/ファイルを提供する、またはビジュアル結果を以前正しいものとして説明する場合に有効にしてください。

参照を装飾ではなく証拠として扱います：

1. すべての報告および表示された症状をリストアップし、ユーザーの具体的な言葉を保持します（「依然として遅い」、「明確ではない」、「尖刺」、「先显示上一个内容」）。
2. 参照のオラクルを特定：最後の良好なコミット/タグ、古いビルド、フィクスチャ、スクリーンショット、ダウンロードされたアーティファクト、またはユーザーの説明からの期待される状態。
3. 編集する前にパス/失敗チェックを定義します。ビジュアルバグの場合、これは狭いスクリーンショットチェックリストとビューをレンダリングするコマンドかもしれません。動作バグの場合、自動化された回帰テストまたは確定的な再現を優先します。
4. 現在と参照を比較し、正確なデルタを名付けてください。ビジュアルの欠陥を「スタイルポーリッシュ」に一般化しないでください。証拠が壊れたレンダー、競合、フォントパイプライン、または状態パスを指している場合。
5. 1 回の試みた修正後に同じ症状が残る場合は、停止して証拠から仮説を再構築してください。証明されていない説明の上にさらなるパッチを積み重ねないでください。

問題が純粋に主観的な UI の味わいである場合、/design にルーティングしてください。レンダリング、状態、タイミング、ビルド出力、フォント生成、または既知の良好なバージョンからの回帰である場合、/hunt にとどまってください。

スコープ爆破モード

根本原因パターンを修正した後、バグが完了したと宣言する前に有効にしてください。同じ形状は N 個の他の場所に隠れることがよくあります。爆破を無視する 1 つのローカル修正は N - 1 個のバグをツリーに残します。

1. パターン署名を抽出します：バグを生成した特定の関数名、正規表現、API 呼び出し、CSS セレクタ、ロック取得、検証スキップ、または入力境界。
2. リポジトリ全体で grep -rn <pattern> を実行します（生成されたディレクトリ、ビルド出力、ベンダー依存関係を除外）。バグ クラス パターン（例：「ロックを欠いている任意のハンドラー」）の場合、リテラルテキストだけではなく周囲の形状をグリップします。
3. すべてのマッチをリストアップしてください。それぞれについて、書面で答えてください：ここでも同じバグですか？修正を選択 / 残す（安全な理由を説明する） / 不確定（ユーザーに尋ねる）。マッチをサイレントでスキップしないでください。
4. 爆破レポートが結果ブロックに入るまで、「修正」と主張しないでください。

一般的なトリガー：

• 1 ページで固定されたビジュアルバグ：同じコンポーネント、レイアウト、またはメディアクエリ breakpoint を使用する他のすべてのページをチェックしてください。
• 1 つのハンドラーで固定された 1 つの競合：同じロックを取得するか、同じ共有状態に触れるすべてのハンドラーをチェックしてください。
• 1 つのエントリポイントでパッチされた 1 つの検証スキップ：同じダウンストリーム シンクに到達するすべてのエントリポイントをチェックしてください。
• 1 つの入力形状の 1 つの正規表現 / パーサー修正：同じ正規表現 / パーサーのすべてのコーラーをチェックしてください。

爆破が無関係なバグを表面化する場合、それらをリストアップしますが、ユーザーが同意しない限り、この PR で修正しないでください。スコープの肥大化はそれ自体のアンチパターンです。

確認または破棄

1 つのターゲット化されたインストルメントを追加します：ログ行、失敗するアサーション、または仮説が正しい場合に失敗する最小テスト。実行してください。証拠が仮説と矛盾する場合は、それを完全に破棄し、学習したことで再び向きを変えてください。証拠が反論する仮説を保持しないでください。

ランタイム証拠の段階

バグが修正されたと主張する前に、このはしごを使用してください：

1. ソーストレース：症状を生成できる正確な関数、状態遷移、ファイル、行、または条件を名付けます。
2. 確定的な再現：症状を生成する最小のコマンド、フィクスチャ、UI パス、またはシナリオを実行または作成します。
3. ログ/状態/キャッシュ：パスが到達したことを証明するランタイム状態を検査します。キュー、DB 行、キャッシュ、一時ファイル、生成された出力、または外部ツールログを含みます。
4. ビルド/テスト：修正を実行する狭いテストまたはビルドを実行してください。
5. 実際のランタイムチェック：UI、ネイティブアプリ、ブラウザ、レンダリング、またはビジュアルバグの場合、アプリ/ページ/アーティファクトを開き、スクリーンショットまたは具体的なチェックリストで表示結果を確認してください。

コンパイルのみは UI、ネイティブアプリ、ビジュアル、レンダリング、または生成されたアーティファクトバグには不十分です。ランタイムチェックが環境で不可能な場合、理由を述べて、確認する正確なスクリーン、コマンド、またはアーティファクトを渡してください。

繰り返される失敗のクラスの場合、2 番目の修正を追加する前に references/failure-patterns.md をロードしてください。

ターゲット化されたログ

ノイズではなく、メスのようにログを使用します。ログを追加する前に、それが答える質問を書いてください：

「このログが X を Y の前に出力する場合、仮説 A はまだ可能です。そうでない場合、仮説 A は間違っています。」

完全なログング プレイブック（二分探索インストルメンテーション、識別ログコンテンツ、境界優先配置、タイミングバグログ、削除規律）のために references/logging-techniques.md をロードしてください。

クイックルール：

1. 症状ではなく実行経路の中点に最初のログを配置してください。そこから二分探索してください。
2. 識別可能な事実のみをログしてください：シーケンス番号、入力キー、取得した分岐、古い/新しい状態、エラーコード。
3. 完了する前に一時的なログを削除してください。プロジェクトのデバッグフラグの後ろに永続的な診断をゲートします。

ログを追加するとが動作を変える場合、それをタイミング、ライフサイクル、または並行処理の問題の証拠として扱います。

落とし穴

何が起こったか	ルール
クライアントペインではなくローカルペインにパッチ	ファイルに触れる前に実行経路を後ろにトレースしてください
MCP がロードされておらず、メソッドを診断する代わりに切り替えた	サーバー ステータス、API キー、メソッドを切り替える前に設定を確認してください
オーケストレーターが実行中と言ったが、TTS ベンダーが誤構成されていた	マルチステージパイプラインでは、各ステージを個別にテストしてください
競合状態が古い状態バグとして診断された	タイミング依存の問題については、状態を見る前にイベントのタイムスタンプと順序を検査してください
どこにでもログを追加しても、バグを説明できなかった	各ログを yes/no の質問として書き直してください。仮説をルールイン/アウトしないログを削除してください
ローカルで再現したが、CI で失敗した	環境を最初に揃えます（ランタイムバージョン、環境変数、タイムゾーン）、その後コードを追求してください
スタックトレースがライブラリの深くを指している	独自のコード 3 フレームに戻ります。バグはほぼ常に依存関係ではなく、そこにあります。
アプリから起動すると機能したが、ファイル関連付け / ドラッグ&ドロップ / ディープリンク / 外部プロキシを介して開くと破損した	ユーザーが説明した正確なエントリポイントを使用して再現してください。アプリ内 init はコールドローンチファイル init とは異なります。ドキュメントが到着したとき、状態は準備できていないかもしれません。
ビルドに合格したが、UI はまだ間違って見えた	ランタイム証拠の段階を上げ、実際にレンダリングされた表面またはアーティファクトを確認してください。

成果

成功形式

根本原因：        [何が間違っていたか、ファイル:行]
修正：               [何が変わったか、ファイル:行]
確認済み：         [修正を証明する証拠またはテスト]
テスト：             [パス/失敗カウント、回帰テストの場所]
回帰ガード：  [テストファイル:行] または [なし、理由]

ステータス：解決済み、警告付きで解決済み（それらを述べてください）、またはブロック済み（不明な点を述べてください）。

回帰ガードルール：繰り返された、または以前「修正」されたバグの場合、修正は次のまで完了しません：

1. 修正されていないコードで失敗し、修正されたコードで成功する回帰テストが存在します。
2. テストは一時ファイルではなく、プロジェクトのテストスイートに存在します。
3. コミットメッセージが、バグが繰り返された理由と、この修正がそれを防ぐ理由を述べています。

ハンドオフ形式（3 つの失敗した仮説の後）

症状：
[元のエラー説明、1 文]

テストされた仮説：
1. [仮説 1] → [テスト方法] → [結果：の理由で除外されました...]
2. [仮説 2] → [テスト方法] → [結果：の理由で除外されました...]
3. [仮説 3] → [テスト方法] → [結果：の理由で除外されました...]

収集された証拠：
- [ログスニペット / スタックトレース / ファイルコンテンツ]
- [再現手順]
- [環境情報：バージョン、設定、ランタイム]

除外されました：
- [排除されている根本原因]

不明な点：
- [まだ不明な点]
- [不足している情報]

推奨される次のステップ：
1. [次の調査方向]
2. [必要な外部ツールまたはアクセス許可]
3. [ユーザーが提供すべき追加コンテキスト]

ステータス：ブロック済み

レンダリングバグモード

次の場合に有効にしてください：「PDF の見た目が悪い」、「ページ区切り問題」、「フォントがレンダリングされていない」、壊れた PDF 出力、または印刷レイアウトが間違っている。

完全な診断チェックリスト（WeasyPrint の癖、フォント読み込み、ページオーバーフロー、ブラウザ印刷 CSS）のために references/rendering-debug.md をロードしてください。必要に応じて静的分析を最初に、その後再現します。

IME / Unicode の問題

入力メソッド、文字レンダリング、またはテキスト エンコーディング バグ（IME 状態、カーソル ドリフト、絵文字分割、コンポジション イベント）の場合、仮説を形成する前に references/ime-unicode.md を最初に確認してください。