- name
- clawlite-investigate
- description
- |
ClawLite Investigate — 系统化 Debug
核心法则
无根因调查则无修复。
修复症状会产生打地鼠式 debug。每个不解决根本原因的修复都会让下一个 bug 更难找到。找到根因，然后修复它。
阶段 1：根因调查
在形成任何假设之前收集上下文。
- 收集症状： 读取错误消息、堆栈跟踪和复现步骤。如果用户没有提供足够的上下文，一次只问一个问题。
- 读取代码： 从症状追溯到潜在原因的代码路径。使用 Grep 查找所有引用，Read 理解逻辑。
- 检查最近的更改：
git log --oneline -20 -- <受影响的文件>这之前能工作吗？什么改变了？回归意味着根因在 diff 中。
- 复现： 你能确定性触发这个 bug 吗？如果不能，在继续之前收集更多证据。
输出："根因假设：..." — 关于什么出错以及为什么的具体、可测试的声明。
阶段 2：模式分析
检查这个 bug 是否匹配已知模式：
| 模式 | 特征 | 查看位置 |
|---|---|---|
| 竞态条件 | 间歇性、时间依赖 | 对共享状态的并发访问 |
| Nil/null 传播 | NoMethodError, TypeError | 可选值上的缺失守卫 |
| 状态损坏 | 数据不一致、部分更新 | 事务、回调、钩子 |
| 集成失败 | 超时、意外响应 | 外部 API 调用、服务边界 |
| 配置漂移 | 本地工作，staging/prod 失败 | 环境变量、特性开关、数据库状态 |
| 陈旧缓存 | 显示旧数据，清除缓存后修复 | Redis、CDN、浏览器缓存 |
还要检查：
TODOS.md中相关的已知问题git log中同一区域的先前修复 — 同一文件中的重复 bug 是架构气味，不是巧合
阶段 3：假设验证
在写任何修复之前，验证你的假设。
- 确认假设： 在可疑的根因处添加临时日志语句、断言或调试输出。运行复现。证据匹配吗？
- 如果假设错了： 返回阶段 1。收集更多证据。不要猜测。
- 三振规则： 如果 3 个假设都失败，停止。使用 AskUserQuestion：
已测试 3 个假设，都不匹配。这可能是架构问题而不是简单的 bug。
A) 继续调查 — 我有新假设：[描述]
B) 升级给人审查 — 这需要了解系统的人
C) 添加日志等待 — 标记区域，下次捕获它红旗 — 如果看到这些，放慢速度：
- "先快速修复一下" — 没有"先"。正确修复或升级。
- 在追踪数据流之前提出修复 — 你在猜测。
- 每个修复都在其他地方揭示新问题 — 错误的层，不是错误的代码。
阶段 4：实现
一旦根因确认：
- 修复根因，不是症状。 消除实际问题最小改变。
- 最小 diff： 改动最少的文件，最少行数更改。抵制重构相邻代码的冲动。
- 写一个回归测试：
- 没有修复时失败（证明测试有意义） - 有修复时通过（证明修复有效）
- 运行完整测试套件。 粘贴输出。不允许回归。
- 如果修复涉及 >5 个文件： 使用 AskUserQuestion 标记影响范围：
此修复涉及 N 个文件。对于 bug 修复来说影响范围很大。
A) 继续 — 根因确实跨越这些文件
B) 拆分 — 现在修复关键路径，延迟其余
C) 重新思考 — 也许有更有针对性的方法阶段 5：验证与报告
全新验证： 复现原始 bug 场景并确认它已修复。这不是可选的。
运行测试套件并粘贴输出。
输出结构化 debug 报告：
DEBUG 报告
════════════════════════════════════════
症状: [用户观察到的]
根因: [实际出了什么问题]
修复: [改变了什么，带文件:行号引用]
证据: [测试输出，显示修复有效的复现尝试]
回归测试: [新测试的文件:行号]
相关: [TODOS.md 项目、同一区域的先前 bug、架构笔记]
状态: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════重要规则
- 3+ 次失败的修复尝试 → 停止并质疑架构。 错误的架构，不是失败的假设。
- 永远不要应用你无法验证的修复。 如果你无法复现和确认，不要发货。
- 永远不要说"这应该修复它"。 验证并证明它。运行测试。
- 如果修复涉及 >5 个文件 → AskUserQuestion 关于影响范围，然后再继续。
- 完成状态：
- DONE — 找到根因，应用修复，写了回归测试，所有测试通过 - DONE_WITH_CONCERNS — 修复但无法完全验证（例如间歇性 bug，需要 staging） - BLOCKED — 调查后根因不清楚，已升级