trellis-break-loop

ループを断ち切る — 深いバグ分析

デバッグが完了したら、「バグを修正 → 忘れる → 繰り返す」というサイクルを断ち切るために、この手順で深く分析してください。

---

分析フレームワーク

修正したばかりのバグを、次の5つの観点から分析してください。

1. 根本原因のカテゴリ

このバグはどのカテゴリに属しますか？

カテゴリ	特徴	例
A. 仕様の欠如	実行方法に関するドキュメントがない	チェックリストのない新機能
B. レイヤー間の契約	レイヤー間のインターフェースが不明確	API が想定と異なる形式を返す
C. 変更の反映漏れ	1か所を変更し、ほかの箇所を見落とす	関数シグネチャを変更したが、呼び出し箇所を見落とす
D. テストカバレッジの不足	単体テストは通るが、統合テストで失敗する	単独では動作するが、組み合わせると壊れる
E. 暗黙の前提	ドキュメント化されていない前提にコードが依存している	タイムスタンプの秒とミリ秒

2. 修正に失敗した理由（該当する場合）

成功するまでに複数の修正を試した場合は、それぞれの失敗を分析してください。

• 表面的な修正：根本原因ではなく、症状を修正した
• 対象範囲の不足：根本原因を特定したが、すべてのケースをカバーできなかった
• ツールの制約：grep で見落とした、型チェックが厳密ではなかった
• メンタルモデル：同じレイヤーばかりを調べ、レイヤーをまたぐ問題を考えなかった

3. 再発防止の仕組み

再発を防ぐには、どのような仕組みが必要ですか？

種類	説明	例
ドキュメント	関係者が把握できるように記録する	思考ガイドを更新する
アーキテクチャ	構造上、エラーが起きないようにする	型安全なラッパー
コンパイル時	厳密な型チェックを行い、逃げ道をなくす	シグネチャの変更でコンパイルエラーが発生する
実行時	モニタリング、アラート、スキャンを行う	孤立したエンティティを検出する
テストカバレッジ	E2E テスト、統合テストを実施する	一連の処理全体を検証する
コードレビュー	チェックリスト、PR テンプレートを使用する	「X を確認しましたか？」

4. 系統的な範囲の拡張

このバグから、どのようなより広範な問題が見えてきますか？

• 類似の問題：同じ問題がほかのどこに存在する可能性がありますか？
• 設計上の欠陥：根本的なアーキテクチャ上の問題はありますか？
• プロセス上の欠陥：開発プロセスに改善の余地はありますか？
• 知識の不足：チームに不足している知識はありますか？

5. 知識の記録

得られた知見をシステムに定着させてください。

• .trellis/spec/guides/ の思考ガイドを更新する
• 関連する .trellis/spec/ ドキュメントを更新する
• 該当する場合は、課題の記録を作成する
• 根本修正のための機能チケットを作成する
• 必要に応じてチェックガイドラインを更新する

---

出力形式

次の形式で分析結果を出力してください。

## Bug Analysis: [Short Description]

### 1. Root Cause Category
- **Category**: [A/B/C/D/E] - [Category Name]
- **Specific Cause**: [Detailed description]

### 2. Why Fixes Failed (if applicable)
1. [First attempt]: [Why it failed]
2. [Second attempt]: [Why it failed]
...

### 3. Prevention Mechanisms
| Priority | Mechanism | Specific Action | Status |
|----------|-----------|-----------------|--------|
| P0 | ... | ... | TODO/DONE |

### 4. Systematic Expansion
- **Similar Issues**: [List places with similar problems]
- **Design Improvement**: [Architecture-level suggestions]
- **Process Improvement**: [Development process suggestions]

### 5. Knowledge Capture
- [ ] [Documents to update / tickets to create]

---

中核となる理念

デバッグの価値はバグを修正することではなく、この種のバグが二度と起きないようにすることにあります。

洞察には3つのレベルがあります。

1. 戦術的：このバグをどう修正するか
2. 戦略的：この種のバグをどう防ぐか
3. 哲学的：思考パターンをどう広げるか

30分の分析で、将来のデバッグにかかる30時間を節約できます。

思考フレームワーク：ベイズ推論

複数の根本原因が考えられ、証拠が不十分な場合は、最初の仮説に固執するのではなく、新たな証拠に応じて確信度を更新してください。

ステップ1：事前確率を設定する

調査を始める前に、何をどのような理由で信じているかを示してください。

仮説	事前確率	推論
H1：[原因 A]	40%	このパターンで最もよくある
H2：[原因 B]	30%	環境を考慮すると妥当
H3：[その他]	30%	その他全般

事前確率の合計は100%でなければなりません。確率を割り当てられない場合は、まず調査してください。

ステップ2：証拠を観察する

見つかった内容を記録し、信頼性を具体的に示してください。

• 具体的に何を観察しましたか？
• 信頼性はどの程度ですか？（テスト出力 > ログメッセージ > ユーザー報告 > 勘）
• 複数の仮説で説明できますか？

ステップ 3：確信度を更新する

各仮説について、次のように考えます。この仮説が正しいとしたら、この証拠が得られる可能性はどのくらいか？

計算よりも、更新の方向が重要です。

• H1 が正しい場合に強く予測される証拠 → H1 の確率が上がる
• H2 と矛盾する証拠 → H2 の確率が下がる
• すべての仮説で同程度にあり得る証拠 → 更新しない

ステップ 4：仮説を見分けられる証拠を探す

同じような証拠をさらに集めるのはやめましょう。上位の仮説間で大きく異なる証拠を探します。

H1 と H3 が拮抗している場合は、「H1 が正しく、H3 が正しくないとしたら、何が見つかるだろうか？」と考え、それを確認します。

ステップ 5：確信度を示す

確信度	対応
90% 以上	修正を進め、監視する
70～90%	対処を進め、フォールバックチェックを追加する
50～70%	確定前に仮説をテストする
50% 未満	さらに証拠が必要。推測しない

証拠が不十分な場合、決めつけた表現は使わないでください。「最も可能性が高い」「可能性はあるが低い」「調査する価値がある」などの表現を使います。

よくある誤謬

誤謬	例	改善策
ベースレートの無視	「テストが失敗した → コードが壊れている」	ほかの原因でテストが失敗する頻度はどのくらいでしょうか？
確証バイアス	「競合状態に違いない。競合を示す証拠を探そう」	最有力の仮説に反する証拠を積極的に探します
アンカリング	「前回はキャッシュの問題だった。今回もたぶんキャッシュだ」	昨日のバグではなく、現在の状況をもとに事前確率を設定します

---

分析後：直ちに行うこと

重要：上記の分析が完了したら、直ちに次の作業を必ず行ってください。

1. 仕様／ガイドを更新する - TODO を列挙するだけでなく、該当するファイルを実際に更新します。

   • クロスプラットフォームの問題の場合 → cross-platform-thinking-guide.md を更新する
   • クロスレイヤーの問題の場合 → cross-layer-thinking-guide.md を更新する
   • コード再利用の問題の場合 → code-reuse-thinking-guide.md を更新する
   • ドメイン固有の問題の場合 → backend/*.md または frontend/*.md を更新する

2. テンプレートを同期する - .trellis/spec/ を更新したら、src/templates/markdown/spec/ に同期します

3. 仕様の更新をコミットする - これが主な成果物であり、分析テキストだけではありません

分析がチャットにとどまるなら、価値はありません。価値があるのは、更新された仕様です。