ループを断ち切れ - 深いバグ分析

デバッグ完了後、このスキルを使用して「バグ修正→忘れる→繰り返す」サイクルを断ち切るための深い分析を実施します。

分析フレームワーク

直近で修正したバグを以下の5つの軸から分析します。

1. 根本原因カテゴリ

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

カテゴリ	特性	例
A. 仕様欠落	実行方法に関するドキュメントがない	チェックリストなしの新機能
B. レイヤー間契約	レイヤー間のインターフェースが不明確	APIが想定と異なる形式を返す
C. 変更伝播の失敗	一箇所を変更したが、他箇所を変更し忘れた	関数シグネチャを変更したが、呼び出し箇所を変更し忘れた
D. テストカバレッジのギャップ	ユニットテストは通るが、結合テストは失敗する	単独では動くが、組み合わせると壊れる
E. 暗黙の前提	コードが文書化されていない前提に依存している	タイムスタンプの単位（秒 vs ミリ秒）

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

成功する前に複数の修正を試みた場合、各失敗を分析します。

表面的な修正: 症状を修正したが、根本原因は修正していない
スコープの不完全性: 根本原因を見つけたが、すべてのケースをカバーしていない
ツールの制限: grepが見逃した、型チェックが厳密でなかった
メンタルモデル: 同じレイヤーだけを見続け、クロスレイヤーを考えなかった

3. 予防メカニズム

再発を防ぐにはどのようなメカニズムが有効ですか？

種類	説明	例
ドキュメント	知識を文書化して周知する	思考ガイドを更新する
アーキテクチャ	構造的にエラーを不可能にする	型安全なラッパー
コンパイル時	厳密な型チェック、回避策なし	シグネチャ変更がコンパイルエラーを発生させる
実行時	モニタリング、アラート、スキャン	孤立エンティティを検出する
テストカバレッジ	E2Eテスト、結合テスト	完全なフローを検証する
コードレビュー	チェックリスト、PRテンプレート	「Xを確認しましたか？」

4. 体系的な拡張

このバグが明らかにする、より広範な問題は何ですか？

類似問題: この問題は他にどこに存在する可能性があるか？
設計上の欠陥: 根本的なアーキテクチャ上の課題はあるか？
プロセス上の欠陥: 開発プロセスの改善点はあるか？
知識のギャップ: チームに不足している理解はあるか？

5. ナレッジキャプチャ

洞察をシステムに定着させます。

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

出力形式

以下の形式で分析を出力してください。

## バグ分析: [簡潔な説明]

### 1. 根本原因カテゴリ
- **カテゴリ**: [A/B/C/D/E] - [カテゴリ名]
- **具体的な原因**: [詳細な説明]

### 2. 修正が失敗した理由（該当する場合）
1. [最初の試行]: [失敗理由]
2. [2回目の試行]: [失敗理由]
...

### 3. 予防メカニズム
| 優先順位 | メカニズム | 具体的なアクション | ステータス |
|----------|-----------|-----------------|--------|
| P0 | ... | ... | TODO/DONE |

### 4. 体系的な拡張
- **類似問題**: [同様の問題がある箇所のリスト]
- **設計改善**: [アーキテクチャレベルの提案]
- **プロセス改善**: [開発プロセスに関する提案]

### 5. ナレッジキャプチャ
- [ ] [更新すべきドキュメント / 作成すべきチケット]

核となる哲学

デバッグの価値はバグを修正することにあるのではなく、この種類のバグを二度と発生させないことにある。

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%未満	さらなる証拠が必要。推測しない

証拠が不完全な場合、二値的な確信を決して表明しないでください。「最も可能性が高い」「ありそうだが低い」「調査する価値あり」を使用します。

よくある誤謬

誤謬	例	修正
ベースレート無視	「テストが失敗した → コードが壊れている」	他の理由でテストが失敗する頻度は？
確証バイアス	「きっと競合状態だ。競合状態の証拠を探そう」	自分の上位仮説に反する証拠を積極的に探す
アンカリング	「前回はキャッシュが原因だった。今回もキャッシュだろう」	昨日のバグではなく、現在のコンテキストから事前確率を確立する

分析後の即時アクション

重要: 上記の分析を完了した後、即座に以下のアクションを実行する必要があります。

spec/guides を更新する - TODOリストを作成するだけでなく、実際に関連ファイルを更新します。
- クロスプラットフォームの問題 → cross-platform-thinking-guide.md を更新
- クロスレイヤーの問題 → cross-layer-thinking-guide.md を更新
- コード再利用の問題 → code-reuse-thinking-guide.md を更新
- ドメイン固有の問題 → backend/*.md または frontend/*.md を更新
テンプレートを同期する - .trellis/spec/ を更新した後、src/templates/markdown/spec/ に同期します。
specの更新をコミットする - これが主要な成果物であり、分析テキストだけではありません。

分析がチャット内に留まっている限り、価値はありません。価値は更新されたspecにあります。

AgentDock - 深いバグ分析