recursive-debugging

recursive-debugging（Phase 1.5）

概述

当需求涉及修复 Bug 或调查意外行为时，临时修复既浪费时间，又会引入新的 Bug。系统化调试会在尝试任何修复之前找到根本原因。

核心原则： 务必先找到根本原因，再尝试修复。只修复症状就是失败。

递归模式调试的铁律：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

触发示例

• 上次更改后测试失败了；调试一下
• 修复空输入时的崩溃
• 调查 API 返回错误数据的原因
• 进行根本原因分析后再做更改

适用场景

以下情况必须执行 Phase 1.5：

• 需求是修复 Bug
• 需要调查测试失败
• 报告了意外行为
• 性能问题
• 集成问题

以下情况尤其适用：

• 时间紧迫（紧急情况容易让人忍不住猜测）
• 看起来“只需快速修复一下”就能解决
• 之前的修复尝试失败了
• 你并未完全理解问题

以下情况也不要跳过：

• 问题看起来很简单（简单的 Bug 也有根本原因）
• 你很赶时间（匆忙处理必然导致返工）
• 经理要求立即修复（系统化处理比反复折腾更快）

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)

系统化调试的四个阶段

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 -> 构建 -> 签名，API -> 服务 -> 数据库）：

在提出修复方案之前，添加诊断检测代码：

针对每个组件边界：

• 记录进入组件的数据
• 记录离开组件的数据
• 验证环境/配置的传递情况
• 检查各层的状态

运行一次以收集证据，确定问题出在哪里，然后再分析证据。

记录在 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 提出单一假设

• 明确陈述：“我认为 X 是根本原因，因为 Y”
• 把它写下来
• 具体明确，不要含糊

3.2 尽量减少测试改动

• 做出测试假设所需的最小更改
• 一次只改变一个变量
• 不要一次修复多个问题

3.3 验证后再继续

• 是否奏效？是 -> 阶段 4
• 没有奏效？提出新的假设
• 不要在此基础上继续叠加修复

3.4 不知道时

• 说明“我不理解 X”
• 不要假装知道
• 寻求帮助
• 进一步调研

记录在阶段 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]

步骤 4：修复总结（交接给阶段 2 规划）

修复根因，而非表象：

4.1 创建失败用例

• 尽可能简洁地复现问题
• 如果可行，编写自动化测试
• 如果没有测试框架，编写一次性测试脚本
• 修复前必须完成
• 这将成为阶段 2 测试策略的一部分

4.2 阶段 2 的根因总结

• 总结发现的根因
• 记录修复方案
• 引用阶段 1.5 中的证据

路由注意事项

如果调试过程中使用了委派审查、外部日志检查或任何其他路由的模型协助，请在选择委派 CLI/模型之前立即重新读取：

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

并遵循当前路由策略，而不要依赖硬编码的模型假设。

记录在阶段 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 次或更多时）

以上情况都意味着：停止。返回阶段 1.5。

常见的流程捷径（停止）

借口	实际情况
“问题很简单，不需要流程”	简单问题也有根因。处理简单 Bug 时，流程很快。
“情况紧急，没时间走流程”	系统化调试比反复猜测和尝试更快。
“先试试这个，再调查”	第一次修复会形成惯例。从一开始就做好。
“确认修复有效后再写测试”	未经测试的修复无法持久。先写测试才能证明修复有效。
“一次修复多项问题能节省时间”	无法确定哪项修复奏效，还会引入新 Bug。
“我看出问题了，让我来修复”	看到表象 != 理解根因。
“再尝试修复一次”（失败 2 次或更多后）	失败 3 次或更多 = 架构问题。质疑处理模式，不要再次修复。

如果修复尝试失败 3 次或更多

表明存在架构问题的模式：

• 每次修复都会在其他位置暴露新的共享状态/耦合/问题
• 修复需要“大规模重构”才能实现
• 每次修复都会在其他地方引发新的表象

停止并质疑根本做法：

• 这种模式从根本上是否合理？
• 我们是否在“纯粹出于惯性坚持下去”？
• 是否应该重构架构，而不是继续修复表象？

记录在阶段 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]

阶段 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 的集成

阶段 1 -> 1.5 过渡

当阶段 1（现状）发现需要修复的 Bug/问题时：

1. 锁定阶段 1（01-as-is.md）
2. 创建阶段 1.5（01.5-root-cause.md），状态设为：DRAFT
3. 执行系统化调试
4. 找到根因后锁定阶段 1.5
5. 带着根因信息进入阶段 2

阶段 1.5 -> 2 过渡

阶段 2（02-to-be-plan.md）基于阶段 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]

参考资料

• 必需： 所有 Bug 修复需求都必须使用此技能
• 触发条件： 需求涉及调试/修复时
• 输出： 01.5-root-cause.md 产物
• 下一步： 阶段 2（目标状态计划）纳入调查结果