ce-debug

デバッグと修正

失敗の根本原因を特定し、ユーザーが選んだ場合は、テストファーストの原則に従って修正します。

完了条件： トリガーから症状までの因果関係を、抜け漏れなく、ファイル名と行番号の根拠とともに示し、検証済みの修正を引き継ぐ（PR、コミット、またはユーザーが選んだ時点で停止する）か、診断のみの要約を提示します。粘り強く続けるのではなく、エスカレーションします： 2～3個の仮説を検証しても確認できない場合、または修正を3回試して失敗した場合は、再試行するのではなく「なぜ」失敗したかを診断します。これが references/investigate.md で説明されている適切なエスカレーションです。仮説を1つずつ立て、変更も一度に1つだけ行います。効果があるものを探るために複数箇所を変更するのは、手当たり次第のデバッグです。

<bug_description> は、このスキルの起動時に渡された内容です。失敗の説明、mode: トークン、または課題への参照（#123、org/repo#123、課題 URL）のいずれかで、ユーザーまたは呼び出し元のスキルから渡されます（mode:pipeline の ce-babysit-pr／lfg は、失敗したジョブとログ末尾を渡します。lfg の不具合ルートは mode:return-to-caller とユーザー自身の参照を渡します）。何も渡されなかった場合は空欄です。

モード

既定は対話型です。調査を行い、Phase 2 の修正選択ゲートを実行してから、Phase 4 の引き継ぎを行います。

mode:pipeline（ce-babysit-pr や lfg などのオーケストレーターが設定）：完全な非対話型で実行し、ブロッキング質問ツールを呼び出してはいけません。<bug_description> からトークンを取り除き、references/pipeline-mode.md を読み、その指示に従ってください。このファイルは、「ユーザーに質問する」すべての箇所に保守的な既定の動作を適用し、Phase 2 の修正ゲートを「収束する不具合は修正し、意見が分かれるものは保留する」に置き換え、Phase 4 の引き継ぎを、status が fixed-and-pushed | fixed-not-pushed | diagnosed-no-fix | flaky-infra | needs-human のいずれかと厳密に一致する構造化された結果に置き換えます。呼び出し元はこの正確な表記に基づいて分岐するため、名前の変更、省略、追加はしないでください。

mode:return-to-caller（lfg が不具合ルートで設定）：非対話型で実行しますが、修正後のすべての工程は呼び出し元が担当します。トークンを取り除き、references/return-to-caller.md を読み、その指示に従ってください。このファイルは Phase 0～3 と、収束する不具合は修正し、それ以外は保留する境界を維持します。Phase 3 の分岐ルールを適用し、修正をフィーチャーブランチに反映し、修正対象ファイルをプッシュせずにコミットします。また、修正後の仕上げとレビューを省略し、status が fixed | diagnosed-no-fix | needs-human | blocked のいずれかと厳密に一致する構造化された結果を返します。表記についても同じルールが適用されます。

ブロッキング質問

このスキルがユーザーに何かを尋ねる場合は、現在のツール一覧にあるホストのブロッキング質問ツールを使用してください（ホスト固有の名前ではなく、機能で判断してください）。現在のツール一覧にあることは、そのツールが存在する証拠です。存在を確かめるために、ユーザー向けの質問ツールを呼び出してはいけません。一致するツールが一覧にあるものの読み込まれていない場合は、ホストのツール検出プリミティブを使ってその機能を読み込んでください。他のホストのツール名を探してはいけません。一致するツールが一覧にない場合、または実際の質問呼び出しでエラーが発生した場合に限り、ホストのチャット画面で番号付きの選択肢を提示します。質問を黙って省略してはいけません。また、回答を得ずにフェーズを終了してはいけません。

証拠に含まれる秘密情報

デバッグでは、生の出力（コマンド結果、取得したペイロード、ログ抜粋など）を頻繁に扱います。また、ハーネスはコマンドの実行直後に出力を表示する場合があるため、秘密情報の確認は事後ではなく、コマンドを組み立てる際に行ってください。認証情報はコマンドラインではなく環境変数に格納します。出力に秘密情報が含まれる可能性がある場合（詳細な HTTP トレース、ダンプしたヘッダー、設定や環境変数の出力など）は、ファイルに出力し、サニタイズした抜粋だけを提示してください。提示、書き込み、コミットする内容に、秘密情報（認証情報、トークン、認証ヘッダー、接続文字列）を含めてはいけません。サニタイズによって診断に必要な情報が失われる場合は、その旨を伝え、ユーザーに確認してください。サニタイズした情報を元に戻してはいけません。

Artifact Root

<root>/ パスを最初に作成するときに限り、<root> を解決します。作成するパスがない実行では、この処理全体を省略します。

アーティファクトパスを作成する前に、CE アーティファクトルート <root> を解決してください。

• 読み取るのは <repo-root>/.compound-engineering/config.yaml の docs_root のみです（<repo-root> = git rev-parse --show-toplevel）。config.local.yaml からは読み取らないでください。未設定の場合、従来どおり <root> は docs です。
• 値が設定されている場合は検証します。リポジトリ相対のディレクトリであり、実パス（シンボリックリンク解決後）がリポジトリ内にとどまり、リポジトリルートでも .git/ 配下でもないことを確認してください。それ以外の場合は、docs_root とその値を示すエラーで停止してください。docs にフォールバックしてはいけません。
• <root> を唯一のアーティファクト保存先として使用します。存在しない場合は作成し、このスキル固有のサブディレクトリを使って各パスを <root>/<subdir> として作成してください。docs を併せて読み取ってはいけません。

実行フロー

5 つのフェーズを順に実行します：0 トリアージ -> 1 調査 -> 2 根本原因 -> 3 修正 -> 4 引き継ぎ。フェーズ 0 の軽微なバグ向けファストパスを除き、フェーズを飛ばしたり、複雑さの段階を設けたりしません。難しいバグでは各フェーズに時間をかけます。フェーズの数を減らしてはいけません。

今すぐ references/investigate.md を読み、フェーズ 0〜2 でその指示に従ってください。課題の取得、再現、環境の健全性確認とダーティーツリーのスタッシュ実験、バックワードトレース、トラッカー／PR 履歴の検索、仮説の根拠付け、エスカレーション表が含まれます。ここに記載するのはゲートのみです。

記録対象の課題。 ユーザーからチケットや課題が渡された場合、どのシステム上のものであっても、そのバグはすでにそこに記録されています。Sentry の課題も Linear のチケットと同様に扱います。識別子と URL をフェーズ 4 まで引き継いでください。入力がスタックトレース、テストパス、または説明のみの場合、この実行には記録対象の課題がありません。これは通常の状態であり、埋めるべき欠落ではありません。課題がなくても修正を提供してください。記録を作るためにチケットを起票してはいけません。また、起票するかどうかをユーザーに尋ねてもいけません。フェーズ 1 のトラッカー検索では過去の作業を調べますが、バグの新たな記録先を作ることはありません。このバグに関する既存のチケットがある場合は、フェーズ 4 でリンクするものであり、作成するものではありません。

軽微なバグ向けファストパス（原因が入力から明らかで、1 行の修正で済み、深いトレースが不要な場合）でも、編集前にフェーズ 2 の修正選択ゲートを通ります。省略できるのは調査の手続きであり、修正を適用するかどうかというユーザーの選択ではありません。

リグレッションテストの選択。 確認済みの不具合に対するリグレッションテストは、既存のテストがその振る舞いをすでにカバーしている場所に追加します。新しいファイルから始めるのではなく、まず既存のテストを確認してください。フェーズ 2 の推奨を作成する前に、追加先と命名規則について references/fix.md を読みます。フェーズ 3 で編集する前だけに読むのではありません。変更によってテストが意図的に検証対象の振る舞いを逆転させるために失敗する場合、期待値が誤っているわけではありません。これは以下で説明する乖離ケースであり、更新せずに保留します。

Phase 2 のゲート：説明してから尋ねる

因果関係の連鎖のゲート： トリガーからすべての段階を経て、観測された症状に至るまでの全体像を、途切れなく説明できるようになるまで Phase 3 に進まないでください。「どういうわけか X が Y につながる」では説明に抜けがあります。調査が行き詰まった場合、最善の仮説に基づいて先に進むことを許可できるのはユーザーだけです。

根本原因を確認したら、調査結果をユーザーに提示するブロックとして記述してください。因果関係の連鎖と file:line 参照、提案する修正と変更対象ファイル、使用・追加・変更・強化するテスト、および既存のテストで検出できるはずだったかどうか、関連するチケットや PR があればその情報と推奨内容への影響を含めてください。すでにこの問題を修正するオープン PR がある場合は、新たな修正案より先にそのリンクを示してください。

ゲートの前に同じターン内で提示すること： 調査結果のブロックをこのターンまたは直前のアシスタントメッセージで完全に記述するまでは、修正方法を選ぶ質問を提示しないでください。ブロッキング質問ツールはモーダルハーネスでは質問文だけを表示するため、「根本原因を確認しました」と伝えただけで質問を出すと、ユーザーは因果関係の連鎖を見ずに選択することになります。選択肢に名前を付けるだけでは調査結果を提示したことにならず、選択後に説明すると約束するのでは遅すぎます。

依頼ですでに次のアクションが許可されていない場合は、Blocking questions に従い、次の 3 つの選択肢を提示して、どの方針で進めるか尋ねてください。明示的な修正依頼は Phase 3 です。明示的な診断のみの依頼は Phase 4 に進みます。mode:pipeline と mode:return-to-caller では質問しません。テストに関する推奨事項は、どちらの場合も診断に含めます。

1. 今すぐ修正する — Phase 3 に進む
2. 診断のみ — あとは自分で対応します — 修正を行わず、Phase 4 の要約を記述してスキルを終了する
3. 設計を再検討する（ce-brainstorm） — 現在の設計のままではバグを修正できない場合に限ります。根本原因が誤ったロジックではなく責務またはインターフェースの誤りである、要件自体が誤っている、または候補となる修正がすべて、もはや成り立たない前提を回避するための対症療法である場合が該当します。規模だけでは設計上の問題とはみなしません。

mode:pipeline と mode:return-to-caller： 質問はしません。Phase 3 に進み、収束的な修正を適用してください。意図的な契約・動作・プロダクト上の決定を覆す修正は、発散的な修正です。意図された動作をアサートする「失敗する」テストもこれに含まれます。こうした修正は適用せず、references/pipeline-mode.md または references/return-to-caller.md に従って保留してください。ここで ce-brainstorm に引き継いではいけません。設計上の問題は needs-human の未解決事項とします。

Phase 3：修正

ユーザーが「診断のみ」を選んだ場合は、Phase 4 の要約に進んでください。「設計を再検討する」を選んだ場合は、制御を ce-brainstorm に引き継ぎ、このスキルを終了します。

ファイルを編集する前に、references/fix.md を読んでください。テストファーストの手順、修正失敗時のルール、多層防御と事後分析のトリガーが記載されています。修正を開始してよいかどうかを決める次の 2 つのルールは、ここにも記載しておきます。

• ブランチ： git status を確認します。ユーザーが変更対象ファイルに未ステージの変更を加えている場合は、編集前に確認してください。現在のブランチがデフォルトブランチなら、確認せずにフィーチャーブランチを作成します。バグに基づいて名前を決め、git checkout -b <name> を実行し、切り替えたブランチ名を伝えてください。デフォルトブランチは main、master、または git rev-parse --abbrev-ref origin/HEAD の出力と比較して判定します。このとき origin/ のプレフィックスを取り除いてください。生の出力は origin/<name> なので、プレフィックスを取り除かずに比較すると一致しません。
• 修正前の作業範囲を記録する： 現在の HEAD、git status --short がクリーンかどうか、既存の変更ファイルを記録してください。その後、作業中に修正対象ファイル（このバグのために変更したテストと実装ファイル）の一覧を管理してください。Phase 4 の 2 つの質問にはこの記録に基づいて回答します。記録がなければ後から再構成できません。

フェーズ 4：引き継ぎ

mode:pipeline — 対話形式の引き継ぎをすべてスキップしてください。 仕上げやレビューの手順、未解決の質問、プレビュー、学習内容を記録する提案はありません。references/pipeline-mode.md に従って収束した修正をコミットしてプッシュし、そこで定義されている構造化された戻り値を出力してください。意見が分かれる項目や人の対応が必要な項目は、そこで後回しにします（スレッドを開くか、呼び出し元の実行レポートにコメントしてください。PR 本文のセクションにはしないでください）。mode:return-to-caller — こちらもスキップしてください。 機能ブランチで修正対象のファイルをコミットし、何もプッシュせず、references/return-to-caller.md で定義されている構造化された戻り値を出力してください。どちらのモードでも、このスキルが最後に書き込むのは戻り値です。これでこのスキルは終了しますが、ターンは終了しません。呼び出し元は同じセッションで実行され、次の手順は戻り値に従います。呼び出し元への引き継ぎを宣言しないでください。このセクションの残りは、対話形式のフローのみを対象としています。

構造化された要約 — 常に最初に記述してください。

## Debug Summary
**Problem**: [What was broken]
**Root Cause**: [Full causal chain, with file:line references]
**Recommended Tests**: [Tests to add/modify to prevent recurrence, with specific file and assertion guidance]
**Fix**: [What was changed — or "diagnosis only" if Phase 3 was skipped]
**Prevention**: [Test coverage added; structural fix or defense-in-depth if applicable, or the structural fix left as follow-up]
**Confidence**: [High/Medium/Low]

フェーズ 3 をスキップした場合は、要約の後で終了してください。ユーザーはすでに、ここから先は自分で進めると伝えています。促さないでください。

フェーズ 3 を実行した場合は、今すぐ references/post-fix-handoff.md を読み、以下の分岐に進む前に、その指示に従ってください。ここでは、修正後の品質手順、コンテキストに応じた上書きの確認、機械的な修正をスキップするルール、無関係なブランチ作業に ce-simplify-code と ce-code-review が及ばないようにするスコープ設定、残った指摘への対処、## Post-Fix Quality ブロック、学びの記録を提案する基準が定義されています。これらはこの本文には記載されていません。以下の分岐では実行するアクションを示すだけで、安全性を保つためのスコープルールは説明していないため、独自に判断して進めることはできません。読み飛ばすと、未レビューの修正をリリースすることになり、レビューが無関係なブランチ作業に及び、受け入れられた指摘がセッションに取り残されます。

ルーティング

ユーザーが提示していないものを一切持ち込まずに修正を着地させます — コミットにも、プッシュにも、PR にも入れません。PR を開くかどうかを尋ねてはいけません。許可はゲートではありません。2 つの問いがハンドオフを決定します。それらには、ブランチがどのように存在するようになったかではなく、フェーズ 3 が記録した修正前のスコープから答えてください。アクション自体を発火させます — プラットフォームのスキル呼び出しプリミティブを介して行い、ユーザーにコマンドを入力するよう伝えるだけにしないでください。

1. コミットに何を含めてよいか — 修正が所有するファイルのみで、それ以外は含めません。 これは、問い 2 でコミットするスキルに対する制約であり、それ自体が独立したアクションになることは決してありません。リモートであるかどうかに関わらず、すべてのルートで成り立ちます。ここではコミットしないでください。

• 修正が所有するファイルに既存の編集が含まれていなかった場合、それらのファイルがコミットのスコープです。それらをコミットするスキルに渡してください。
• 修正が所有するファイルにすでにユーザーの編集が含まれていた場合、どのコミットもそれらを分離できません。ce-commit はファイル単位でグループ化し、ファイルを分割することは決してありません。何かがコミットされる前に、そのファイルをユーザーの編集込みでコミットするか、修正を未コミットのままにするか、中止するかを、(ブロッキングの問いに従って)尋ねてください。最初の回答のみが続行します。他の 2 つはハンドオフを終了させるため、問い 2 は決して実行されず、何もコミットされません。何が、なぜ残されたのかを伝えてください。どの選択肢も、エージェントがユーザーの代わりに選ぶことのできない何かを失うため、この問いは存続します。フェーズ 3 の確認はファイルの編集を対象としており、ユーザーの編集を修正とともにコミットすることを決して対象としていませんでした。

2. 誰がコミットするか、そしてそれがリリースされるか。 これらのうち正確に 1 つが実行されます。

• リリースするのは、次の 3 つすべてが成り立つ場合です。修正前のツリーがクリーンであったこと、ブランチ上のいかなるものもユーザーがすでに提示していない作業ではないこと、そして origin が PR 対応であること — つまり gh が実際に PR を開ける場所であること。これらは、目の前にあるリポジトリに合う方法で確認してください。2 つの事実が、見た目よりもこれを明白でなくします。

  • ce-commit-push-pr はブランチ全体をプッシュし、その PR はあなたの修正だけでなくブランチ上のすべてのコミットに及びます。したがって、問いはあなたの差分ではなくブランチに関するものです。また、PR を作成する前にプッシュするため、gh が PR を開けないリモートはブランチを PR なしで公開したままにします。
  • すでにプッシュ済みであることは、すでに提示済みであることではありません。オープンな PR 内のコミットはレビュー下にあるため、提示済みであり、この実行は 2 つ目の PR を開くのではなくその PR を更新します。バックアップや CI のトリガーのためにプッシュされたコミットは提示済みではなく、最初の PR がそれらを公開してしまいます。ローカルの ref ではなくリモートと比較してください。ローカルブランチは、フェーズ 3 が分岐した可能性のあるデフォルトブランチを含め、それ自体がプッシュ済みの内容より先行していることがあります。

  3 つすべてを確認できない場合は、代わりにローカルルートを取ってください。それが安全な方向であり、プレビューはその代わりにはなりません。そうでなければ、何が、どのブランチでコミットされるのか、PR が開かれるのか更新されるのかをプレビューし、次に branding:on を付けて ce-commit-push-pr スキルを呼び出します。 これは問い 1 のスコープでコミットするため、先にコミットしないでください。プレビューは声明であり、問いではありません。結果の PR URL を提示してください。

• ローカルにとどめるのは、それら 3 つのいずれかが失敗した場合です。問い 1 のスコープで ce-commit スキルを呼び出し、何もプッシュしないでください。何が、なぜローカルにとどまったのか、そして要求があればプッシュして PR を開くことを 1 行で伝えてください。先に尋ねないでください。ローカルコミットは可逆です。

• git リポジトリでない場合: 何もコミットされません。サマリーと品質ブロックの後に停止してください。

文脈上のオーバーライド(「スキルから PR を開かないで」、「コミットのみ」、「修正後に停止」) — ユーザーが言ったことに従い、それが求められたことであればコミットせずにここで停止してください。曖昧な口調の合図はオーバーライドではありません。

PR がオープンした後 — リファレンスの学習キャプチャ基準を適用してください。そのゲートが修正を適格と判断した場合にのみ、キャプチャを提案し、ユーザーが受け入れたら ce-compound スキルを呼び出し、次にそれが実際に書き込んだ、または更新した成果物のみをコミットしてプッシュし、オープンな PR がそれらを取り込むようにしてください。何も書き込まなければ、ドキュメントのコミットなしで終了してください。