debug

调试

输出语言： 使用用户自己的语言回答并编写产物（与用户的消息一致，而不是与仓库的历史记录一致）。

概述

将系统化的根因调试与完成前验证相结合。

核心原则：先有证据，再修复；先有证据，再声称“已修复”。

声明：“正在使用 debug 来……”

适用场景

• 任何 Bug、偶发测试失败、构建/CI 失败、意外行为或性能异常
• 尤其是在时间紧迫时（“就快速修一下”）
• 在声称“完成”“通过”或“已修复”之前

**不适用场景：**没有故障的纯全新功能开发（使用 grill / write-spec / write-plan / tdd）。

铁律

1. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
2. NO "FIXED" / "PASSING" / "DONE" CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE IN THIS TURN.

违反字面要求，就是违背其精神。

工作流（按阶段依次执行）

阶段 1 — 调查（暂不修复）

1. 阅读完整的错误信息 / 堆栈 / 日志（不要略读）
2. 稳定地复现问题——如果无法复现，就收集数据，不要猜测
3. 检查近期变更（git diff、提交、配置、环境）
4. 多组件系统：在边界（输入 → 输出）添加埋点，找出问题出在哪里
5. 从异常值向上追溯到源头；计划从源头修复

为这些步骤创建待办事项；在阶段 1 明确根因之前，不要修改生产逻辑。

阶段 2 — 模式

• 在仓库中找到类似的正常工作路径
• 对比正常与异常路径；列出所有差异
• 记录依赖项 / 假设

阶段 3 — 假设

• 提出一个假设：“X 是根因，因为 Y”
• 设计能够证伪该假设的最小测试/探针
• 如果假设错误 → 提出新假设（不要随意叠加变更）

阶段 4 — 通过 TDD 修复

1. tdd + test-design：编写一个失败的回归测试来锁定 Bug
2. 确认 RED 阶段失败的原因正确
3. 最小化修复 → GREEN
4. 在使用任何表示成功的措辞之前，先验证（见下文）

阶段 5 — 声明前验证（必须）

在声称已修复/通过/完成/结束之前：

1. 确定能够证明该声明的命令
2. 重新运行该命令（完整命令）
3. 读取退出码和失败信息
4. 只有此时才能声明，并提供证据

声明	所需证据
测试通过	测试运行输出，失败数为 0
Bug 已修复	重新测试原始症状 + 回归测试通过
构建成功	构建退出码为 0
满足要求	根据计划/规范逐项核对

回归测试的红绿证明：修复前失败 → 修复后通过（可行时，通过实际或模拟回退检查）。

合理化借口表

借口	事实
“显而易见的一行修复”	仍然需要找到原因并编写回归测试。
“现在应该可以了”	运行验证。
“我很有把握 / 累了”	信心 ≠ 证据。
“记录了一些东西，够了”	边界证据必须指出问题出在哪里。
“先修复，之后再理解”	这样只会引发另一个 Bug。

危险信号 — 停止

• 在说明根因之前就提出修复方案
• 使用“应该”“大概”“似乎”等措辞表示成功
• 未重新运行测试/验证症状就提交修复或创建 PR
• 对无关文件进行大范围随意修改
• 跳过失败的回归测试

检查清单

• 已根据证据说明根因
• 已观察到回归测试（tdd）先 RED 后 GREEN
• 本轮已运行全新的验证命令
• 声明中包含相关证据
• 没有顺手修改无关内容

交接

过渡关卡——修复发布前，询问用户（使用一次 AskUserQuestion；绝不自动继续）：

A) Recommended: Proceed → review (then commit-and-push)
B) Review first — run **review** on the fix (`references/code.md`; upstream = the failing repro), then return to this gate
C) Adjust — back into debug for the un-locked edge, then return to this gate
D) Something else (I will type it)

• 原因是结构问题 → solid
• 发布修复 → review + commit-and-push