Systematic Debugging

---
name: systematic-debugging
description: バグ・エラー・テスト失敗・予期しない挙動・ビルド失敗に遭遇した時、修正案を出す前に使用する根本原因調査の規律。4フェーズ（根本原因調査→パターン分析→仮説検証→実装）を順守させ、症状への場当たり修正と当てずっぽうの変更連発を防ぐ。修正3回失敗でアーキテクチャ自体を疑う。境界: 原因特定後の修正実装はwriting-code、提出前のdiff確認はself-review。
allowed-tools: Read, Grep, Glob, Bash(git:*)
---

# Systematic Debugging

当てずっぽうの修正は時間を浪費し、新しいバグを生む。**Core principle: 修正を試みる前に、必ず根本原因を特定する。症状への修正は失敗である。**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

Phase 1を完了していないなら、修正を提案できない。**ルールの文言をすり抜けることは、ルールの精神に違反することと同じ**（「今回は事情が違うから」は成立しない）。

緊急時・「すぐ直せそう」に見える時・既に何度か修正を試した後こそ、このプロセスを使う。体系的なデバッグは、guess-and-checkの試行錯誤より**速い**。

## The Four Phases

各フェーズを完了してから次へ進む。

### Phase 1: 根本原因調査

1. **エラーメッセージを精読する** — スタックトレースを最後まで読む。行番号・ファイルパス・エラーコードを控える。エラーメッセージはしばしば解決策そのものを含む
2. **確実に再現する** — 確実に発火させる手順を確立する。再現できないなら、修正でなくデータ収集を続ける
3. **直近の変更を確認する** — git diff・最近のコミット・依存やconfigの変更・環境差分
4. **原因を一次情報で特定する** — エラーの原因を公式ドキュメント（context7 / WebSearch）で確認する（グローバル規約「推測禁止・調査先行」と同一。推測での修正着手は禁止）
5. **複数コンポーネント系では境界に診断ログを仕込む** — 各コンポーネント境界で入る値・出る値・環境変数の伝播を記録し、一度実行して**どの層で壊れるか**の証拠を取ってから、その層を調べる
6. **データフローを遡る** — エラーが出た場所ではなく、不正な値の発生源を突き止める（[references/techniques.md](references/techniques.md) の root-cause-tracing）

### Phase 2: パターン分析

1. 同じコードベースで**動いている類似コード**を探す
2. リファレンス実装・公式サンプルがあるなら**全行読む**（斜め読みで「パターンだけ真似る」ことが部分理解バグを生む）
3. 動くものと壊れているものの**差分をすべて列挙する**（「これは関係ないはず」と決めつけない）

### Phase 3: 仮説検証

1. **単一の仮説を明文化する** — 「Xが根本原因だと考える。理由はY」と書き出す
2. **最小の変更で検証する** — 一度に1変数。複数の修正を同時に入れない（何が効いたか切り分け不能になり、新しいバグを生む）
3. 外れたら**新しい仮説を立てる**。修正を上に積まない
4. 分からないなら「Xが分からない」と明言し、調査を続けるかユーザーに聞く。分かったふりをしない

### Phase 4: 実装

1. **失敗するテストケースを先に作る**（最小の再現。フレームワークがなければ使い捨てスクリプトでよい）
2. **単一の修正を実装する** — 特定した根本原因だけを直す。「ついでの改善」やリファクタを混ぜない。修正コードを書く前に `/writing-code` を発動する（原則を記憶で思い出して書くのは不可。実際にスキルを読むこと）
3. **検証する** — テストが通り、他のテストが壊れておらず、元の問題が実際に解消したことを確認してから完了を報告する
4. 根本原因の修正後、必要なら多層の防御を追加する（[references/techniques.md](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 — 修正を提案する前のチェック

- [ ] エラーメッセージ・スタックトレースを最後まで読んだ
- [ ] 再現手順を確立した（または再現不能と明記した）
- [ ] 原因を一次情報（公式ドキュメント・実測した証拠）で特定した
- [ ] 仮説を1文で明文化した（「Xが根本原因。理由はY」）
- [ ] 提案する変更は1つで、根本原因に対応している（症状への対処ではない）

調査を尽くしても真に環境起因・タイミング起因・外部起因の場合は、調査内容を記録した上で適切なハンドリング（リトライ・タイムアウト・エラーメッセージ・監視）を実装する。ただし「根本原因なし」の大半は調査不足である。

---

出典: obra/superpowers（MIT License）を翻案。詳細はリポジトリルートの NOTICE.md を参照。