recursive-debugging

recursive-debugging（Phase 1.5）

概要

要件にバグの修正や予期しない動作の調査が含まれる場合、その場しのぎの修正は時間を無駄にし、新たなバグを生みます。体系的なデバッグでは、修正を試みる前に根本原因を特定します。

基本原則： 修正を試みる前に、必ず根本原因を特定してください。症状だけを修正するのは失敗です。

recursive-mode デバッグの鉄則：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

トリガーの例

• Tests are failing after the last change; debug it
• Fix crash on empty input
• Investigate why the API returns wrong data
• Do a root cause analysis before making changes

使用する場面

Phase 1.5 が必須となる場合：

• 要件がバグ修正である
• テストの失敗を調査する必要がある
• 予期しない動作が報告された
• パフォーマンスの問題がある
• 統合に関する問題がある

特に使用する場合：

• 時間に追われている（緊急時は推測に頼りがちです）
• 「ちょっとした修正で済む」と思える
• 以前の修正が失敗した
• 問題を十分に理解できていない

次の場合も省略しないでください：

• 問題が単純に見える（単純なバグにも根本原因があります）
• 急いでいる（焦ると手戻りが確実に増えます）
• マネージャーから今すぐ直すよう求められている（体系的な方法のほうが、試行錯誤を繰り返すより速いです）

Phase 1.5 の挿入

デバッグが必要な場合、Phase 1.5 は Phase 1（AS-IS）と Phase 2（TO-BE Plan）の間に挿入されます：

Phase 0: 00-requirements.md
    ->
Phase 1: 01-as-is.md (captures current behavior)
    ->
Phase 1.5: 01.5-root-cause.md <- NEW (this skill)
    ->
Phase 2: 02-to-be-plan.md (includes fix plan based on root cause)

体系的なデバッグの 4 つのフェーズ

digraph debugging_phases {
    rankdir=TB;
    
    phase1 [label="Step 1:\nRoot Cause Investigation", shape=box, style=filled, fillcolor="#ffcccc"];
    phase2 [label="Step 2:\nPattern Analysis", shape=box, style=filled, fillcolor="#ffffcc"];
    phase3 [label="Step 3:\nHypothesis & Testing", shape=box, style=filled, fillcolor="#ccffcc"];
    phase4 [label="Step 4:\nFix Implementation", shape=box, style=filled, fillcolor="#ccccff"];
    
    phase1 -> phase2 -> phase3 -> phase4;
    
    // Feedback loops
    phase3 -> phase1 [label="hypothesis\nfailed", style=dashed];
    phase4 -> phase1 [label="fix\nfailed", style=dashed];
}

ステップ 1：根本原因の調査

修正を試みる前に、必ず行うこと：

1.1 エラーメッセージを注意深く読む

• エラーや警告を読み飛ばさない
• 多くの場合、正確な解決策が記されています
• スタックトレースを最後まで読む
• 行番号、ファイルパス、エラーコードを記録する

Phase 1.5 の成果物に記録：

## Error Analysis

**Error Message:** [verbatim]
**Stack Trace:** [key frames]
**File:Line:** [locations]
**Error Code:** [if applicable]
**Key Insight:** [what the error is telling you]

1.2 一貫して再現できる状態にする

• 確実に発生させられますか？
• 正確な手順は何ですか？
• 毎回発生しますか？
• 再現できない場合は、推測せず、さらにデータを集める

Phase 1.5 の成果物に記録：

## Reproduction Verification

**Steps:**
1. [exact step]
2. [exact step]
3. [exact step]

**Reproducible:** Yes / No / Intermittent
**Frequency:** [X out of Y attempts]
**Deterministic:** Yes / No

1.3 最近の変更を確認する

• 原因となりうる変更は何ですか？
• Git の差分、最近のコミット
• 新しい依存関係、設定の変更
• 環境の違い

Phase 1.5 の成果物に記録：

## Recent Changes Analysis

**Git History:** [relevant commits]
**Dependency Changes:** [package.json, requirements.txt, etc.]
**Config Changes:** [relevant files]
**Environment:** [OS, runtime versions]
**Likely Culprit:** [most suspicious change]

1.4 複数コンポーネントのシステムで証拠を集める

システムに複数のコンポーネントがある場合（CI -> build -> signing、API -> service -> database）：

修正を提案する前に、診断用の計測を追加する：

各コンポーネントの境界で：

• コンポーネントに入るデータを記録する
• コンポーネントから出るデータを記録する
• 環境や設定が引き継がれていることを確認する
• 各層の状態を確認する

一度実行して、どこで問題が発生するかを示す証拠を集めてから、その証拠を分析します。

Phase 1.5 の成果物に記録：

## Multi-Layer Evidence

**Layer 1: [Component Name]**
- Input: [data]
- Output: [data]
- Status: WORKING / BROKEN

**Layer 2: [Component Name]**
- Input: [data from Layer 1]
- Output: [data]
- Status: WORKING / BROKEN

**Failure Boundary:** Layer X -> Layer Y
**Root Cause Location:** [specific component]

1.5 データフローをたどる

呼び出しスタックの深い位置でエラーが発生している場合：

逆向きにたどる：

• 不正な値はどこで発生していますか？
• どの呼び出し元が、不正な値を渡しましたか？
• 発生源を見つけるまで上流へたどる
• 症状ではなく、発生源を修正する

Phase 1.5 の成果物に記録：

## Data Flow Trace

**Error Location:** [file:line - function]
**Bad Value:** [what was wrong]

**Call Stack Trace:**
1. [deepest] `functionA()` at fileA:line - received [value]
2. `functionB()` at fileB:line - passed [value]
3. `functionC()` at fileC:line - passed [value]
4. [source] `functionD()` at fileD:line - ORIGIN of bad value

**Root Cause:** [source location] - [explanation]

ステップ 2：パターン分析

修正する前にパターンを見つける：

2.1 正常に動作する例を探す

• 同じコードベース内で、類似した正常動作するコードを見つける
• 壊れているものと似ていて、正常に動作するものは何ですか？

2.2 リファレンスと比較する

• パターンを実装する場合、リファレンス実装を完全に読む
• 流し読みせず、すべての行を読む
• 適用する前に、パターンを十分に理解する

2.3 相違点を特定する

• 正常に動作するものと壊れているものの違いは何ですか？
• どんなに小さくても、違いをすべて列挙する
• 「関係ないはずだ」と決めつけない

2.4 依存関係を理解する

• ほかにどのコンポーネントが必要ですか？
• 必要な設定、コンフィグ、環境は何ですか？
• どのような前提を置いていますか？

Phase 1.5 の成果物に記録：

## Pattern Analysis

**Working Example:** [file:location]
**Broken Code:** [file:location]

**Key Differences:**
| Aspect | Working | Broken |
|--------|---------|--------|
| [X] | [value] | [value] |
| [Y] | [value] | [value] |

**Likely Cause:** [difference that explains the bug]
**Dependencies:** [what the code needs to work]

ステップ 3：仮説と検証

科学的な手法：

3.1 仮説を 1 つ立てる

• 「Y であるため、X が根本原因だと考えます」と明確に述べる
• 書き留める
• 曖昧にせず、具体的にする

3.2 最小限の検証を行う

• 仮説を検証するために、可能な限り小さな変更を加える
• 一度に変更する変数は 1 つだけにする
• 複数の問題を同時に修正しない

3.3 続行する前に検証する

• 動作しましたか？ はい → Phase 4
• 動作しませんでしたか？ 新しい仮説を立てます
• 修正を重ねて追加してはいけません

3.4 わからない場合

• 「X が理解できません」と伝えます
• わかったふりをしません
• 助けを求めます
• さらに調査します

Phase 1.5 の成果物に記録します：

## Hypothesis Testing

### Hypothesis 1
**Statement:** [clear hypothesis]
**Rationale:** [why you think this]
**Test:** [minimal change to verify]
**Result:** [confirmed/rejected]
**Evidence:** [output/observation]

### Hypothesis 2 (if needed)
[...]

**Confirmed Root Cause:** [final hypothesis]

Step 4: 修正の概要（Phase 2 の計画への引き継ぎ）

症状ではなく、根本原因を修正します：

4.1 失敗するテストケースを作成する

• 可能な限りシンプルに再現します
• 可能であれば自動テストにします
• フレームワークがない場合は、単発のテストスクリプトを作成します
• 修正を始める前に必ず用意します
• これが Phase 2 のテスト戦略の一部になります

4.2 Phase 2 向けの根本原因の概要

• 判明した根本原因を要約します
• 修正方法を記録します
• Phase 1.5 の証拠を参照します

ルーティングへの注意

デバッグで委任されたレビュー、外部ログの調査、その他のルーティングされたモデルの支援を利用する場合は、委任先の CLI／モデルを選択する直前に、次のファイルを再読してください：

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

ハードコードされたモデルの想定ではなく、現在のルーティングポリシーに従ってください。

Phase 1.5 の成果物に記録します：

## Root Cause Summary

**Root Cause:** [one sentence]
**Location:** [file:line]
**Explanation:** [paragraph explaining why]
**Fix Approach:** [high-level]
**Test Strategy:** [how to verify fix]

## Phase 1.5 Gate

Coverage: [Did we find root cause?]
Approval: [Ready to proceed to Phase 2 with fix plan?]

危険な兆候 ― 作業を止めて手順に従う

次のように考えていることに気づいたら：

• 「とりあえず急いで修正して、調査は後で」
• 「X を変更して、動くか試してみよう」
• 「変更をいくつか加えてから、テストを実行しよう」
• 「テストは省略して、手動で確認すればいい」
• 「おそらく X だろう。修正してみよう」
• 「完全には理解していないけれど、これで動くかもしれない」
• データフローを追跡する前に解決策を提案する
• 「もう一度だけ修正を試そう」（すでに 2 回以上試した場合）

これらはすべて、作業を止めて Phase 1.5 に戻るべきというサインです。

よくある手順の省略（停止）

言い訳	実態
「問題は単純だから、手順は必要ない」	単純な問題にも根本原因はあります。単純なバグなら、手順に従ってもすぐに対応できます。
「緊急だから、手順に従う時間がない」	体系的なデバッグのほうが、当てずっぽうで試行錯誤するより速いです。
「まずこれを試してから調査しよう」	最初の修正が、その後の進め方を決めます。最初から正しく行いましょう。
「修正を確認してからテストを書こう」	テストされていない修正は定着しません。まずテストで確かめます。
「一度に複数の修正をすれば時間を節約できる」	何が有効だったのか切り分けられず、新たなバグを引き起こします。
「問題がわかったから、修正しよう」	症状が見えていることと、根本原因を理解していることは同じではありません。
「もう一度だけ修正を試そう」（2 回以上失敗した後）	3 回以上失敗した場合は、アーキテクチャ上の問題です。パターンを疑い、再度修正するのはやめましょう。

修正を 3 回以上試しても失敗した場合

アーキテクチャ上の問題を示すパターン：

• 修正のたびに、別の箇所で共有状態、結合、または問題が明らかになる
• 修正の実施に「大規模なリファクタリング」が必要になる
• 修正するたびに、別の場所で新たな症状が発生する

作業を止め、基本原則を問い直します：

• このパターンは根本的に妥当ですか？
• 「惰性だけでこの方針にこだわって」いませんか？
• 症状の修正を続けるのではなく、アーキテクチャをリファクタリングすべきですか？

Phase 1.5 に記録します：

## Architectural Concern

**Fix Attempts:** [number]
**Pattern:** [what happens with each fix]
**Recommendation:** [architectural change vs. symptom fix]
**Next Steps:** [escalate, refactor, or accept risk]

Phase 1.5 成果物のテンプレート

ファイル： /.recursive/run/<run-id>/01.5-root-cause.md

Run: `/.recursive/run/<run-id>/`
Phase: `01.5 Root Cause Analysis`
Status: `DRAFT` | `LOCKED`
Inputs:
- `/.recursive/run/<run-id>/01-as-is.md`
- [relevant addenda]
Outputs:
- `/.recursive/run/<run-id>/01.5-root-cause.md`
Scope note: This document records systematic debugging process and identified root cause.

## TODO

- [ ] Replace every placeholder section with the concrete root-cause evidence for this run.

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Subagent Capability Probe: [what proved availability or unavailability]
Delegation Decision Basis: [why self-audit or delegation was chosen]

## Error Analysis

[Section 2.1 - verbatim errors, stack traces]

## Reproduction Verification

[Section 2.2 - exact steps, reproducibility]

## Recent Changes Analysis

[Section 2.3 - git history, dependencies]

## Evidence Gathering

[Section 2.4 - multi-layer diagnostics if applicable]

## Data Flow Trace

[Section 2.5 - backward trace to source]

## Pattern Analysis

[Section 3 - working vs broken comparison]

## Hypothesis Testing

[Section 4 - scientific method log]

## Root Cause Summary

**Root Cause:** [one sentence]
**Location:** [file:line]
**Detailed Explanation:** [paragraph]
**Fix Strategy:** [approach for Phase 2]
**Test Plan:** [how to verify]

## Requirement Completion Status

- `R1` | `investigated` | Root cause identified at [location] | Evidence: [section]

## Traceability

- R1 (Bug fix requirement) -> Root cause identified at [location] | Evidence: [section]

## Coverage Gate

- [ ] Error messages analyzed
- [ ] Reproduction verified
- [ ] Recent changes reviewed
- [ ] Data flow traced to source
- [ ] Pattern analysis completed
- [ ] Hypothesis tested and confirmed
- [ ] Root cause documented
- [ ] Fix strategy defined

Coverage: PASS / FAIL

## Approval Gate

- [ ] Root cause identified (not just symptom)
- [ ] Fix approach clear
- [ ] Test strategy defined
- [ ] No "quick fixes" attempted
- [ ] Ready to proceed to Phase 2

Approval: PASS / FAIL

LockedAt: [when locked]
LockHash: [sha256]

recursive-mode との連携

Phase 1 から 1.5 への移行

Phase 1（AS-IS）で、修正が必要なバグ／問題が見つかった場合：

1. Phase 1（01-as-is.md）をロックします
2. Status: DRAFT として Phase 1.5（01.5-root-cause.md）を作成します
3. 体系的なデバッグを実施します
4. 根本原因が見つかったら Phase 1.5 をロックします
5. 根本原因の知識をもとに Phase 2 に進みます

Phase 1.5 から 2 への移行

Phase 2（02-to-be-plan.md）は Phase 1.5 を基盤とします：

## Root Cause Reference

Root cause identified in `01.5-root-cause.md`:
- Location: [file:line]
- Cause: [summary]
- Full analysis: [reference]

## Fix Plan

Based on root cause analysis:
1. [specific fix steps]
2. [test strategy from Phase 1.5]

参考情報

• 必須： すべてのバグ修正要件でこのスキルを使用します
• 適用条件： 要件にデバッグ／修正が含まれる場合
• 出力： 01.5-root-cause.md 成果物
• 次のステップ： Phase 2（TO-BE Plan）で調査結果を反映します