bug-investigator

バグ調査

バンドルされたランタイム

以下の CLI 行を実行する前に、先頭の SSF を node "<plugin-root>/scripts/spec-superflow.mjs" に置き換えてください。<plugin-root> は、このファイルの 2 つ上の階層にある絶対ディレクトリです。SSF をそのまま実行したり、PATH にある ssf を呼び出したりしないでください。

基本原則： 修正を試みる前に、根本原因を特定してください。症状への対処は失敗です。

新規の直接的な変更／計画された変更

フェーズ移行や個別のデバッグ記録を設けずに、再現、根本原因の追跡、焦点を絞った修正を 1 つ行い、検証まで進めて調査します。役立つ失敗の証拠は、既存の進捗記録に残してください。同じ未解決の問題で 3 回失敗した場合は判断を下す必要があります。無関係な調査結果を共通の回数枠に加算しないでください。タスクブックやサブエージェントは不要です。以下の詳細な従来のプロトコルは、既存のデバッグ状態がある場合や、それが必要な調査に適用されます。

鉄則

根本原因を調査する前に修正してはいけません。フェーズ 1 を完了していない場合、修正を提案することはできません。

使用する場面

技術的な問題全般に使用してください。テストの失敗、バグ、予期しない動作、パフォーマンスの問題、ビルドの失敗、統合の問題が含まれます。特に、時間に追われている場合、「すぐに直せそう」と思える場合、すでに複数の修正を試した場合、または問題を十分に理解していない場合に有効です。

問題が「単純そう」だから、あるいは「急いでいる」からといって省略しないでください。体系的にデバッグするほうが、試行錯誤を繰り返すより速く進みます。

4 つのフェーズ

次のフェーズに進む前に、各フェーズを完了してください。

フェーズ 1：根本原因の調査

1. エラーメッセージを注意深く読む：スタックトレース、行番号、ファイルパス、エラーコードには、解決策そのものが記載されていることがよくあります
2. 一貫して再現する：毎回同じ手順で再現できますか？再現できない場合は、推測せず、さらにデータを集めてください
3. 最近の変更を確認する：git diff、最近のコミット、新しい依存関係、設定の変更、環境の違いを確認してください
4. 複数コンポーネントから成るシステム：各コンポーネントの境界に診断用の計測を追加します。各レイヤーに入るデータと出るデータを記録してください。証拠を集めるために一度実行し、どのコンポーネントが失敗しているのかを分析します
5. データフローを追跡する：逆方向に追跡し、不正な値がどこから来ているのかを調べます。発生源を見つけるまで追跡を続けてください。症状ではなく発生源を修正します

フェーズ 2：パターン分析

1. 同じコードベースで、類似したコードの正常な例を探します
2. リファレンスと比較し、リファレンス実装を最後まで読みます
3. 正常に動作するものと壊れているものの違いを、どんなに小さくてもすべて特定します
4. 依存関係を理解します。他のコンポーネント、設定、構成、環境、前提条件を確認します

フェーズ 3：仮説と検証

科学的手法に従います。単一の仮説（「Y であるため、根本原因は X だと考えます」）を立て、可能な限り小さな変更で検証します（変数は一度に 1 つ）。次に進む前に結果を確認してください。うまくいかなかった場合は、新しい仮説を立てます。修正を追加してはいけません。わからない場合は、そう伝えて助けを求めてください。

フェーズ 4：実装

1. 失敗するテストケースを作成する — 可能であれば、自動化された最も単純な再現手順を用意します。build-executor の TDD ルールに従ってください
2. 修正を 1 つだけ実装する — 根本原因に対処し、一度に 1 つ変更します。「ついでに」改善することは避けてください
3. 修正を検証する — テストは成功しましたか？リグレッションはありませんか？問題は解決しましたか？
4. 修正が機能しない場合：試行回数を数えます。3 回未満ならフェーズ 1 に戻ります。3 回以上なら停止し、アーキテクチャを見直してください（DP-5）

DP-5：デバッグのエスカレーション（3回以上の失敗）

修正に3回以上失敗した場合は、アーキテクチャに問題があります。各修正によって別の箇所に新たな問題が明らかになる場合は、アーキテクチャが適切ではありません。

修正に失敗するたびに、その失敗時の出力を変更ディレクトリ内の実ファイルに保存し、その後、個別の試行として記録します。

Full および legacy Hotfix では、このコマンドの実行前に最新かつ有効な実行計画が必要です。必要に応じて SSF execution recommend と SSF execution plan で計画を確立してください。Quick、Tweak、lightweight、direct Hotfix では、計画を必要としない契約を維持します。有効なワークフローの実行記録によってデバッグが許可され、台帳ではその実行記録と現在のワークフロー、アーティファクト、契約の各ハッシュに試行が紐付けられます。デバッグコマンドは、実行記録が存在しない、または置き換えられている場合や、必須の計画が古い場合に拒否します。

SSF debug attempt record <change-dir> \
  --id <unique-attempt-id> \
  --summary "<what was tried and why it failed>" \
  --evidence <change-local-failure-log>

すべての試行台帳を表示するには、SSF debug attempt show <change-dir> --json を使用してください。Wave Review の修復失敗は別の証拠であり、デバッグ試行には数えません。

証拠に裏付けられた個別の試行を3回以上行ったら、そこで停止し、アーキテクチャ上の判断についてユーザーと話し合ってください。DP-5 を記録できるのは、ユーザーが明示的に選択した後だけです。

SSF debug escalate <change-dir> \
  --decision <continue|abandon> \
  --reason "<user-confirmed decision>" \
  --confirm

生の SSF state set を使って dp_5_* を書き込まないでください。これらのフィールドはデバッグ台帳によって保護されています。ユーザーが abandon を選択した場合は、保護された DP-5 の実行記録を記録してから abandoned に遷移してください。

危険な兆候 — フェーズ1に戻る

「まずは簡単に直して、調査は後で」／「とりあえず X を変更してみて」／「テストは省略して、手動で確認します」／「たぶん X なので、修正します」／「よく分かりませんが、これでうまくいくかもしれません」／「もう1回修正を試す」（2回以上失敗した後）／データの流れを追跡する前に解決策を提案する。

これらはすべて、停止してフェーズ1に戻るべき兆候です。 修正に3回以上失敗した場合は、アーキテクチャを疑ってください。

クイックリファレンス

フェーズ	主な作業	成功基準
1. 根本原因	エラーを読み、再現し、変更を確認し、証拠を集める	何が起きたのか、なぜ起きたのかを理解する
2. パターン	動作する例を探し、比較する	違いを特定する
3. 仮説	理論を立て、最小限のテストを行う	仮説を確認する、または新しい仮説を立てる
4. 実装	テストを作成し、修正し、検証する	バグが解決し、テストに合格する

根本原因が見つからない場合

本当に環境依存、タイミング依存、または外部要因による問題である場合は、調査した内容を記録し、適切な処理（再試行、タイムアウト、エラーメッセージ）を実装して、監視を追加してください。ただし、「根本原因が見つからない」ケースの95%は、調査が不十分なことが原因です。

例外処理

• 解析の失敗：未加工の出力を報告し、説明を求めてください。推測してはいけません
• ファイルの欠落：直ちにエスカレーションしてください。通常のデバッグではありません
• ユーザーによる中断：再開時に調査レポートを読み直し、最後に完了したフェーズから続行してください