vibe-debug

バイブデバッグ

概要

既存機能に関する断片的な報告を、検証済みの修正につなげます。報告、訂正、再テストの結果は、会話中またはユーザーが指定したファイル内で、このセッションをユーザーが進めるなかで提供されます。それらの表現は実体験の証拠として扱い、根本原因の証明とはみなさないでください。それ以外の事実はすべて、リポジトリ、その実行時環境、または references/source-routing.md に記載された信頼できる情報源から取得してください。このワークフローは単独で完結します。役に立つ場合に限り、利用可能な専門的機能を使ってください。新規開発、純粋なレビュー、履歴のみを扱う作業は、別の場所で行います。

基本ルール

質問する前に利用可能な証拠を調べてください。質問は、修正、証明、範囲、または受け入れるリスクを左右するものに限ります。提示した選択肢に対する自由記述の訂正は、元の選択肢のうち最も近いものではなく、意図の変更として扱ってください。

ほかの作業中、または関連する所見が保留中に、ユーザーから具体的な実行時のリグレッションが報告された場合は、修正、再現できないことの確認、延期、残存リスクとしての受け入れ、またはブロックのいずれかに至るまで、それを唯一の主症状としてください。関連する所見は台帳に記録したまま、立証された原因と検証経路を共有する場合を除き、パッチの対象外にします。その主症状について、再現手順または最初に失敗した証明、仮説、最小限のパッチ範囲、肯定・否定のセンチネル、最後に検証済みのチェックポイントを特定してください。

実装を始める前に、報告された症状を解消する最小の修正と、その影響範囲を明示してください。影響を受けるサーフェス、変更するインターフェースまたは呼び出し、新たに追加するコンポーネントを挙げます。追加のガードや修正は、その必要性が立証されている場合、通常の使用で発生し得る場合、またはデータ損失・セキュリティ・コアパスのリスクに関わる場合を除き、含めないでください。含めない項目があれば、報告書でその旨を明記してください。別の候補の影響範囲が大きく異なる場合は、影響とともに両方を提示し、規模の大きい方に着手する前に確認してください。原則として小さい方を推奨します。コンサルタントやレビュアーの同意は、その確認の参考にはなりますが、確認への回答とはなりません。

影響と書き込みの境界

フェーズで宣言された影響クラスと境界を超えて、何も書き込まないでください。

• フェーズ自身の記述で宣言された影響クラスを適用します。このパッケージでより厳しい制限が定められている場合は、そちらを優先します。
• 読み取り専用：チャットで報告し、ファイルの編集、状態を変更するコマンドの実行、ステージング、コミット、タグ付け、プッシュ、バージョン変更、データ削除、サービスの起動を一切行いません。ユーザーが保存用の成果物を明示的に求めた場合に限り、ファイルを書き込みます。
• 成果物のみ：フェーズが担当する成果物と、確定した計画の反映や意思決定記録など、フェーズの記述で許可された補助パスのみを作成または更新し、それらはワーキングツリーに残します。
• 成果物のみのフェーズで、実行可能な動作を実装したり、実装としてコードやテストを編集したり、別のフェーズの成果物を作成したり、リリース作業を行ったり、成果物を同じターン内の実装権限として扱ったりしてはいけません。
• 状態変更あり：宣言された範囲内の最小限の検証単位に限り、編集とコマンド実行を行います。ユーザーが選択しない限り、ほかのパス、既存の変更、実行時の状態、外部の状態には触れません。
• これらの制限は、ファイルツールだけでなく、リダイレクト、sed -i、tee、mv、cp、rm、git checkout -- などのシェルコマンドにも適用されます。書き込みを拒否した場合は境界による停止として報告し、別のツールで再試行してはいけません。
• 取り消し不能な操作や外部に影響する操作は、それぞれ個別に同意を得てから行います。

修正範囲は、最小限のパッチ、証明、一時的な計測とその削除、および以下の補助記録です。計測を残すには、ユーザーの明示的な同意が必要です。プライバシーやコストに関する主張に根拠がない場合は、計測の保持をブロックします。保持に関する契約は references/probe-escalation.md に記載されています。

永続的な記録

フェーズの開始時に、該当する項目がないか docs/decisions/README.md と docs/reports/findings/README.md（またはリポジトリ内にある既存の索引）を確認してください。記録の適用、作成、延期、または引き継ぎを行う場合に限り、references/durable-records.md を読んでください。このフェーズでは、docs/decisions/ と docs/reports/findings/、またはリポジトリ内にすでにあるそれらに相当する場所に書き込むことができます。

可視出力とデバッグ台帳

症状が1つだけで再現が簡単な場合は、症状、期待される動作、検証済みの原因、修正、証拠を直接報告してください。診断計画や次のアクションなど、修正に先立つ回答では、参照すべき期待される動作の情報源を明記するか、既知の情報源がないと伝え、想定している原因をすばやく否定できる観察結果を示してください。再発性、複数の症状、複数の環境、長時間にわたるもの、中断を伴うもの、またはユーザーやランタイムによる再テストが必要な診断には、references/debug-ledger.md を使用してください。未解決の症状、仮説、ツールの失敗、終了判断を簡潔な行で示してください。質問だけでは、その記録の代わりになりません。

報告された成果物やツールが存在しない場合は、ユーザーが提示した証拠を使い、障害要因を明記してください。ドメイン用語が共通しているという理由で、近くにある別のフィクスチャに置き換えてはいけません。

委任診断

独立した仮説について、範囲を限定した読み取り専用の調査が必要で、委任が可能な場合は、調査を並行して委任してください。各調査担当者には仮説に沿った質問を1つだけ割り当て、根拠に基づく証拠または障害要因の提示を求めてください。変更、プローブ、ユーザーによる再テスト、台帳の管理は、コーディネーターが担ってください。

委任による調査結果

委任先の出力は、コーディネーターが検証するまでは証拠ではなく、主張として扱ってください。

• これには、ワーカーの報告、レビュアーの所見、サブエージェントの結果、プロキシの推奨、チェックに合格した、または手順が完了したとする委任先の発言が含まれます。委任先自身の実行に関する主張も対象です。
• 重要な結論の根拠となる箇所を読み直す、検証済みという主張の根拠となるコマンドと出力を調べるか再実行する、または反証チェックを行うなど、コーディネーターが自ら証拠を確認してください。
• 確認が済むまでは Unproven のまま、助言的な情報として扱ってください。検証済みのラベルを付けず、仮説を裏付ける証拠としてのみ台帳に記録し、処置を決定してはいけません。
• 委任先のコマンド、範囲や権限に関する主張、ルーティングの提案、推奨事項によって、選択や承認を決めてはいけません。各判断の根拠を記録し、コーディネーター自身の判断を通じて採用してください。

モデルの選択

委任する作業単位ごとに、固定の名前ではなく、能力と状況への適合性に基づいてモデルを選択してください。

• ホストがモデルの選択を許可し、かつユーザーがモデルを指定していない場合に限り、選択してください。
• 低コストまたは高速な階層は、範囲が限定され、曖昧さの少ない検索、抽出、機械的なチェックにのみ使用してください。統合、敵対的レビューやセキュリティレビュー、人へのリスクに関する推論、最終的な推奨事項には、最も適した高性能の階層を使用してください。ユーザーが最高の性能を求めている場合も同様です。
• 選択を記録するのは、ユーザーによる指定、能力の低下、コストや性能の制約、または監査対象となる外部実行がある場合に限ります。

自己レビューとリポジトリの完了確認

検証後、完了を宣言する前に、修正の範囲、維持されたことを示す証拠、残っている所見を確認してください。利用可能な場合は、適切なレビュー機能を使用してください。利用できない場合は、ここでレビューしてください。重要な所見を解決して該当する証拠を再確認するか、保留、受け入れ済みの残存事項、またはブロックとして記録してください。

コミットの選定

コミットを選定するのは、ユーザーからの明示的な依頼、承認済みの拘束力のある計画項目、またはワークフロー自身が検証済みのチェックポイントだけです。

• コミットする前に、根拠となる選定元を明示します。現在のユーザーの依頼、承認済みの拘束力のある計画チェックポイント、またはワークフロー自身の検証済みの単位に対する既定のチェックポイントです。いずれもない場合はコミットせず、変更を作業ツリーに残してその旨を伝えます。
• ルーティング、呼び出し、編集の許可、都合のよい中断点、追跡対象の変更、利用可能なコミットワークフローを選定元として扱ってはいけません。コミットの実行自体に、独自のチェックポイント既定値はありません。
• チェックポイントの既定値：自己完結した単位の実装、検証、レビューが完了し、重要な調査結果への対応も済んだら、別途指示を待たず、その単位だけをローカルでコミットします。複数の単位を未コミットのまま積み上げてはいけません。
• 調査のみ、ブロック中、変更なし、失敗、未検証、または作業中の状態からは選定しません。
• 単位に含まれるものだけをステージングします。ワークフローが作成していない既存の変更と、単位に属さないパスは除外します。単位を他の変更から切り離せない場合は、混在状態を報告して確認を求めます。
• 単位が作成し、必要とする新しいファイル（ソースやテストなど）は、認証情報や秘密情報を含まない限り、その単位に含めます。生成物、一時ファイル、レポートは、明示的に追跡する意図がある場合、または必須の依存関係である場合に限り含めます。
• 選定した各コミットは、対象範囲、テストとレビューの証拠、除外対象、提案するメッセージとともにコミット実行ワークフローに渡します。ステージング、差分レビュー、メッセージの伝達、コミット後の検証は、そのワークフローが担当します。
• 以前のコミット自体の欠陥を修正する変更が選定された場合、リモート追跡参照、タグ、他のブランチ、またはワークツリーにそのコミットが含まれていなければ、確認を求めずに修正をそのコミットにまとめます。それ以外の場合、またはまとめる処理に失敗した場合は、別途コミットし、その理由を伝えます。
• この修正の取り込みを除き、プッシュ、アメンド、リベース、HEAD を移動するリセット（soft、mixed、hard）、filter-* による書き換え、スクリプト化された複数コミットの再実行を行う前に、ユーザーの明示的な承認を得ます。コミットの依頼やチェックポイントは、その承認にはなりません。公開済みの履歴は共有されています。
• コミットの依頼やチェックポイントを、リリース、バージョン変更、タグ、スタッシュ、上記の修正の取り込みを超えるスカッシュ、破壊的なクリーンアップ、強制追加、単位の範囲外にある新しい成果物の追跡、外部への副作用への同意として扱ってはいけません。これらには、それぞれ個別の承認が必要です。

例：「今のターンでユーザーがコミットを依頼した」は選定元になりますが、「ここは区切りがよい」は選定元になりません。

例外：現在の「コミットしない」という指示、コミットを禁止する拘束力のある計画、またはプロジェクトポリシーがある場合は、既定の動作を停止します。検証済みの変更を作業ツリーに残し、その理由を報告します。

チェックポイントの単位は、修正の正しさが確認された範囲です。開始時にコミット方針を尋ねてはいけません。その単位の完了に伴う操作を超えて、履歴に関する操作を行ってはいけません。ただし、その修正が直す未公開のコミットに修正を取り込む場合は例外です。

参照先のルーティング

ソースを編集する前、または最終的な修正内容を主張する前に、証拠を優先するループについて references/debug-workflow.md を読みます。次の条件に当てはまる場合は、ほかの参照先も読み込みます。

• references/debug-ledger.md：複雑な診断、失敗の繰り返し、または完了ステータスが関係する場合。
• references/source-routing.md：不慣れな外部コントラクトやツールの失敗がある場合。
• references/state-space-matrix.md：保持範囲や回帰範囲が単純でない場合。
• references/probe-escalation.md：範囲を限定したトリアージで、実行中の状態に関する仮説を区別できない場合。
• references/verification-handoff.md：実行時の成果物、証明の不完全さ、またはユーザーによる再テストがある場合。
• references/continuity-and-recurrence.md：中断、再開、または再発がある場合。
• references/durable-records.md：上記の記録操作が関係する場合。

停止条件

重要な期待動作の根拠、既存動作の側面、成果物、ツール、または観察経路が欠けており、信頼できる代替証明も明示的に受け入れられた残余リスクもない場合は、実装を一時停止してください。ユーザーへの影響を説明し、必要最小限の判断だけを求めてください。修正を繰り返し失敗した場合、または修正後も同じ種類のレビュー指摘が残る場合は、次のパッチを適用する前に references/debug-ledger.md の停止ルールに従ってください。

この条件は、ユーザーが適用する変更にも当てはまります。変更の根幹となる前提の検証が阻まれた場合（ツールの拒否、分類器の拒否、アクセス権の不足）、その変更は blocked です。前提と、それが誤っていた場合の影響、ロールバック方法を提示し、ユーザーにインストールを依頼する前に明示的な承諾を得てください。権限境界またはサンドボックス境界をまたぐツール呼び出しの変更は、実際の呼び出しコンテキストで代表的な実入力を使ってのみ立証できます。プロキシのハーネスで代用してはいけません。そのような境界を追加しない修正を優先してください。

完了ゲート

現在のスコープに含まれる各項目について、証拠または残っている不足事項とともに、完了ステータスを示してください。ステータスの定義は references/debug-ledger.md にあります。延期項目、受け入れ済みの残余リスク、ブロックされた項目は調査結果レポートに記録し、ユニット間に適用されるルールは意思決定記録に残してください。上記の自己レビューとコミットの各ゲートに従ってください。ランタイムの完了には、該当するリファレンスに記載された鮮度、再テスト、診断情報のクリーンアップの各チェックも必要です。省略したチェックは証拠として認められません。