debug

デバッグ

出力言語： 回答と成果物は、ユーザー自身の言語で記述してください（リポジトリの履歴ではなく、ユーザーのメッセージに合わせます）。

概要

体系的な根本原因のデバッグと完了前の検証を組み合わせます。

基本原則：修正の前に証拠を。修正済みと主張する前に証拠を。

宣言：「debug を使用して……」

使用する場面

• あらゆるバグ、不安定なテスト、ビルド／CI の失敗、予期しない動作、原因不明のパフォーマンス問題
• 特に時間に追われている場合（「手早く修正をひとつだけ」など）
• 「完了」「合格」「修正済み」と主張する前

使用しない場面： 失敗のない、純粋なグリーンフィールド機能の開発（grill ／ write-spec ／ write-plan ／ tdd を使用してください）。

鉄則

1. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
2. NO "FIXED" / "PASSING" / "DONE" CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE IN THIS TURN.

文言に違反することは、精神にも違反することです。

ワークフロー（フェーズ — 順番どおりに実施）

フェーズ 1 — 調査（まだ修正しない）

1. エラー／スタックトレース／ログをすべて読む（流し読みしない）
2. 一貫して再現する — 再現できない場合は、推測せずデータを集める
3. 最近の変更を確認する（git diff、コミット、設定、環境）
4. 複数コンポーネントのシステムでは、境界（入力 → 出力）に計測を追加して、どこで問題が起きるかを確認する
5. 不正な値を発生源までさかのぼり、発生源で修正する計画を立てる

これらの手順の ToDo を作成します。フェーズ 1 で根本原因を明示するまで、本番ロジックを編集しないでください。

フェーズ 2 — パターン

• リポジトリ内で正常に動作する類似の経路を見つける
• 正常な経路と壊れた経路を比較し、すべての違いを列挙する
• 依存関係／前提条件を記録する

フェーズ 3 — 仮説

• 仮説はひとつにする：「Y が理由で、X が根本原因です」
• 仮説を反証するための最小限のテスト／調査方法を設計する
• 誤っていた場合は新しい仮説を立てる（手当たり次第に変更を重ねない）

フェーズ 4 — TDD で修正

1. tdd と test-design を使い、バグを再発させない回帰テストを書く
2. 適切な理由で RED になることを確認する
3. 最小限の修正を行い、GREEN にする
4. 成功を示す表現を使う前に、以下の検証を行う

フェーズ 5 — 主張する前に検証（必須）

修正済み／合格／完了／完成と伝える前に、以下を行います。

1. 主張を裏付けるコマンドを特定する
2. そのコマンドを新たに実行する（コマンド全体を実行）
3. 終了コードと失敗を確認する
4. その後でのみ、証拠を添えて主張する

主張	必要な証拠
テスト合格	テスト実行結果、失敗 0 件
バグ修正済み	元の症状の再テスト ＋ 回帰テストの合格
ビルド成功	ビルドの終了コード 0
要件達成	計画／仕様に照らしたチェックリスト

回帰テストのレッド・グリーンの証明：修正なしで失敗 → 修正後に合格（可能であれば、頭の中で確認するか、実際に修正を戻して確認する）。

正当化の一覧

言い訳	実態
「明らかなワンライナーです」	それでも原因の特定と回帰テストが必要です。
「これで動くはずです」	検証を実行してください。
「自信がある／疲れている」	自信は証拠ではありません。
「何か記録したので、これで十分です」	境界の証拠で、問題がどこで起きているかを示す必要があります。
「先に修正して、理解は後で」	そうするとバグが 2 つ発生します。

危険信号 — 作業を止める

• 根本原因を明示する前に修正を提案する
• 成功を「はず」「おそらく」「と思われる」と表現する
• 新たなテスト／症状の証拠なしに修正をコミット／PR する
• 無関係なファイルに手当たり次第の変更を加える
• 失敗する回帰テストを省略する

チェックリスト

• 根本原因を証拠とともに明示した
• 失敗する回帰テスト（tdd）が RED から GREEN になるのを確認した
• 今回の作業中に検証コマンドを新たに実行した
• 主張にその証拠を含めた
• 無関係なついでの編集をしていない

引き継ぎ

移行ゲート — 修正をリリースする前に、ユーザーに確認します（AskUserQuestion を 1 回使用し、自動的に次へ進まないでください）。

A) Recommended: Proceed → review (then commit-and-push)
B) Review first — run **review** on the fix (`references/code.md`; upstream = the failing repro), then return to this gate
C) Adjust — back into debug for the un-locked edge, then return to this gate
D) Something else (I will type it)

• 原因が構造にあった → solid
• 修正をリリースする → review ＋ commit-and-push