ClawLite Investigate — 系统化调试

核心原则

不找到根本原因，就不算修复。

只修复症状会导致打地鼠式的调试。每一个不解决根本原因的修复，都会让下一个 Bug 更难定位。找到根本原因，然后再修复它。

阶段 1：根本原因调查

在形成任何假设之前，先收集上下文信息。

1. 1. 收集症状： 读取错误信息、堆栈跟踪和复现步骤。如果用户没有提供足够的上下文，一次只问一个问题。

1. 2. 阅读代码： 从症状出发，追溯可能导致问题的代码路径。使用 Grep 查找所有引用，使用 Read 理解逻辑。

1. 3. 检查最近的变更：

这个功能之前能正常工作吗？是什么发生了变化？回归意味着根本原因就在差异中。

1. 4. 复现： 你能稳定地触发这个 Bug 吗？如果不能，在继续之前收集更多证据。

输出：根本原因假设：... — 一个关于哪里出错以及为什么出错的具体、可测试的声明。

阶段 2：模式分析

检查这个 Bug 是否匹配已知的模式：

同时检查：

• - TODOS.md 中相关的已知问题
• git log 中同一区域的先前修复 — 同一文件中的重复 Bug 是架构问题，不是巧合

阶段 3：假设验证

在编写任何修复代码之前，先验证你的假设。

1. 1. 确认假设： 在可疑的根本原因处添加临时的日志语句、断言或调试输出。运行复现步骤。证据是否匹配？

1. 2. 如果假设错误： 返回阶段 1。收集更多证据。不要猜测。

1. 3. 三振出局规则： 如果 3 个假设都失败，停止。使用 AskUserQuestion：

已测试 3 个假设，均不匹配。这可能是一个架构问题，而不是简单的 Bug。

A) 继续调查 — 我有新的假设：[描述]
B) 升级给人审查 — 这需要了解系统的人
C) 添加日志等待 — 标记区域，下次捕获它

危险信号 — 如果看到这些，放慢速度：

• - 先快速修复一下 — 没有先这回事。要么正确修复，要么升级。
• 在追踪数据流之前就提出修复方案 — 你只是在猜测。
• 每次修复都在其他地方暴露出新问题 — 是修复的层级错了，不是代码错了。

阶段 4：实现

一旦根本原因确认：

1. 1. 修复根本原因，而不是症状。 用最小的改动消除实际问题。

1. 2. 最小差异： 改动最少的文件，最少的代码行数。抵制重构相邻代码的冲动。

1. 3. 编写一个回归测试：

1. 4. 运行完整的测试套件。 粘贴输出。不允许出现回归。

1. 5. 如果修复涉及超过 5 个文件： 使用 AskUserQuestion 标记影响范围：

此修复涉及 N 个文件。对于 Bug 修复来说影响范围很大。
A) 继续 — 根本原因确实跨越这些文件
B) 拆分 — 现在修复关键路径，延迟其余部分
C) 重新思考 — 也许有更有针对性的方法

阶段 5：验证与报告

全新验证： 复现原始的 Bug 场景并确认它已被修复。这不是可选项。

运行测试套件并粘贴输出。

输出结构化的调试报告：

DEBUG 报告
════════════════════════════════════════
症状: [用户观察到的现象]
根本原因: [实际出了什么问题]
修复: [改变了什么，附带文件:行号引用]
证据: [测试输出，显示修复有效的复现尝试]
回归测试: [新测试的文件:行号]
相关: [TODOS.md 项目、同一区域的先前 Bug、架构笔记]
状态: DONE | DONEWITHCONCERNS | BLOCKED
════════════════════════════════════════

重要规则

• - 3 次或以上失败的修复尝试 → 停止并质疑架构。 是架构错了，不是假设错了。
• 永远不要应用你无法验证的修复。 如果你无法复现并确认，就不要发布。
• 永远不要说这应该能修复它。 要验证并证明它。运行测试。
• 如果修复涉及超过 5 个文件 → AskUserQuestion 关于影响范围，然后再继续。
• 完成状态：