| name | systematic-debugging |
| description | バグ・エラー・テスト失敗・予期しない挙動・ビルド失敗に遭遇した時、修正案を出す前に使用する根本原因調査の規律。4フェーズ（根本原因調査→パターン分析→仮説検証→実装）を順守させ、症状への場当たり修正と当てずっぽうの変更連発を防ぐ。修正3回失敗でアーキテクチャ自体を疑う。境界: 原因特定後の修正実装はwriting-code、提出前のdiff確認はself-review。 |
Systematic Debugging
当てずっぽうの修正は時間を浪費し、新しいバグを生む。Core principle: 修正を試みる前に、必ず根本原因を特定する。症状への修正は失敗である。
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Phase 1を完了していないなら、修正を提案できない。ルールの文言をすり抜けることは、ルールの精神に違反することと同じ（「今回は事情が違うから」は成立しない）。
緊急時・「すぐ直せそう」に見える時・既に何度か修正を試した後こそ、このプロセスを使う。体系的なデバッグは、guess-and-checkの試行錯誤より速い。
The Four Phases
各フェーズを完了してから次へ進む。
Phase 1: 根本原因調査
- エラーメッセージを精読する — スタックトレースを最後まで読む。行番号・ファイルパス・エラーコードを控える。エラーメッセージはしばしば解決策そのものを含む
- 確実に再現する — 確実に発火させる手順を確立する。再現できないなら、修正でなくデータ収集を続ける
- 直近の変更を確認する — git diff・最近のコミット・依存やconfigの変更・環境差分
- 原因を一次情報で特定する — エラーの原因を公式ドキュメント（context7 / WebSearch）で確認する（グローバル規約「推測禁止・調査先行」と同一。推測での修正着手は禁止）
- 複数コンポーネント系では境界に診断ログを仕込む — 各コンポーネント境界で入る値・出る値・環境変数の伝播を記録し、一度実行してどの層で壊れるかの証拠を取ってから、その層を調べる
- データフローを遡る — エラーが出た場所ではなく、不正な値の発生源を突き止める（references/techniques.md の root-cause-tracing）
Phase 2: パターン分析
- 同じコードベースで動いている類似コードを探す
- リファレンス実装・公式サンプルがあるなら全行読む（斜め読みで「パターンだけ真似る」ことが部分理解バグを生む）
- 動くものと壊れているものの差分をすべて列挙する（「これは関係ないはず」と決めつけない）
Phase 3: 仮説検証
- 単一の仮説を明文化する — 「Xが根本原因だと考える。理由はY」と書き出す
- 最小の変更で検証する — 一度に1変数。複数の修正を同時に入れない（何が効いたか切り分け不能になり、新しいバグを生む）
- 外れたら新しい仮説を立てる。修正を上に積まない
- 分からないなら「Xが分からない」と明言し、調査を続けるかユーザーに聞く。分かったふりをしない
Phase 4: 実装
- 失敗するテストケースを先に作る（最小の再現。フレームワークがなければ使い捨てスクリプトでよい）
- 単一の修正を実装する — 特定した根本原因だけを直す。「ついでの改善」やリファクタを混ぜない。修正コードは
/writing-code スキルの原則に従って書く
- 検証する — テストが通り、他のテストが壊れておらず、元の問題が実際に解消したことを確認してから完了を報告する
- 根本原因の修正後、必要なら多層の防御を追加する（references/techniques.md の defense-in-depth）
停止条件: 修正3回失敗はアーキテクチャの問題
修正が失敗するたびに数える。3回失敗したら、4回目を試みる前に停止してアーキテクチャ自体を疑う。
兆候: 修正のたびに別の場所で新しい問題が出る / 修正に大規模リファクタが必要になる。これは外れた仮説ではなく、間違ったアーキテクチャのサイン。ユーザーと構造の議論をしてから先へ進む。
Red Flags — 内心にこれが浮かんだら停止してPhase 1へ
- 「とりあえず暫定対応で、調査は後で」
- 「試しにXを変えてみて動くか見よう」
- 「複数まとめて変えてテストを回そう」
- 「たぶんXだから、そこを直そう」
- 「完全には理解していないが、これで動くかもしれない」
- データフローを遡る前に解決策を提案している
- 「もう1回だけ修正を試したい」（既に2回以上失敗している時）
Common Rationalizations（言い訳と現実）
| 言い訳 | 現実 |
|---|
| 「単純なissueだからプロセス不要」 | 単純なバグにも根本原因がある。単純ならプロセスも速く終わる |
| 「緊急なので時間がない」 | 体系的デバッグはguess-and-checkの試行錯誤より速い |
| 「まず試して、ダメなら調査する」 | 最初の1手がその後のパターンを決める。最初から正しくやる |
| 「複数の修正をまとめれば時間短縮」 | 何が効いたか切り分けられず、新しいバグを生む |
| 「問題は見れば分かる」 | 症状が見えること ≠ 根本原因を理解していること |
| 「もう1回だけ」（2回以上失敗後） | 3回失敗はアーキテクチャの問題。同じ層で修正を重ねない |
Gate Function — 修正を提案する前のチェック
調査を尽くしても真に環境起因・タイミング起因・外部起因の場合は、調査内容を記録した上で適切なハンドリング（リトライ・タイムアウト・エラーメッセージ・監視）を実装する。ただし「根本原因なし」の大半は調査不足である。
出典: obra/superpowers（MIT License）を翻案。詳細はリポジトリルートの NOTICE.md を参照。
