clawlite-investigate

中文：系统化 debug 与根因调查框架（调查-分析-假设-验证），只做针对根因的修复。适用于 bug 调试、异常行为分析、服务报错排查，提供可复验结论。 日本語：調査・分析・仮説・検証の4段階で根本原因を追うデバッグフレーム。表面的修正を避け、再発防止を意識した実証可能な結論を生成。 한국어：조사/분석/가설/검증 4단계로 근본 원인을 찾는 디버그 스킬. 증상 처리에 그치지 않고 검증 가능한 결론과 재발 방지 중심의 수정 방향을 제시. Español：Framework de depuración en 4 fases (investigar, analizar, hipótesis y validar). Soluciona desde la causa raíz, ideal para bugs y fallos de comportamiento con resultados verificables.

ClawLite Investigate — 系统化 Debug

核心法则

无根因调查则无修复。

修复症状会产生打地鼠式 debug。每个不解决根本原因的修复都会让下一个 bug 更难找到。找到根因，然后修复它。

---

阶段 1：根因调查

在形成任何假设之前收集上下文。

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

2. 读取代码： 从症状追溯到潜在原因的代码路径。使用 Grep 查找所有引用，Read 理解逻辑。

3. 检查最近的更改：

   bash

   git log --oneline -20 -- <受影响的文件>
   

   这之前能工作吗？什么改变了？回归意味着根因在 diff 中。

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

输出："根因假设：..." — 关于什么出错以及为什么的具体、可测试的声明。

---

阶段 2：模式分析

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

模式	特征	查看位置
竞态条件	间歇性、时间依赖	对共享状态的并发访问
Nil/null 传播	NoMethodError, TypeError	可选值上的缺失守卫
状态损坏	数据不一致、部分更新	事务、回调、钩子
集成失败	超时、意外响应	外部 API 调用、服务边界
配置漂移	本地工作，staging/prod 失败	环境变量、特性开关、数据库状态
陈旧缓存	显示旧数据，清除缓存后修复	Redis、CDN、浏览器缓存

还要检查：

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

---

阶段 3：假设验证

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

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

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

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

   text

   已测试 3 个假设，都不匹配。这可能是架构问题而不是简单的 bug。
   
   A) 继续调查 — 我有新假设：[描述]
   B) 升级给人审查 — 这需要了解系统的人
   C) 添加日志等待 — 标记区域，下次捕获它
   

红旗 — 如果看到这些，放慢速度：

• "先快速修复一下" — 没有"先"。正确修复或升级。
• 在追踪数据流之前提出修复 — 你在猜测。
• 每个修复都在其他地方揭示新问题 — 错误的层，不是错误的代码。

---

阶段 4：实现

一旦根因确认：

1. 修复根因，不是症状。 消除实际问题最小改变。

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

3. 写一个回归测试：

   • 没有修复时失败（证明测试有意义）
   • 有修复时通过（证明修复有效）

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

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

   text

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

---

阶段 5：验证与报告

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

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

输出结构化 debug 报告：

text

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

---

重要规则

• 3+ 次失败的修复尝试 → 停止并质疑架构。 错误的架构，不是失败的假设。
• 永远不要应用你无法验证的修复。 如果你无法复现和确认，不要发货。
• 永远不要说"这应该修复它"。 验证并证明它。运行测试。
• 如果修复涉及 >5 个文件 → AskUserQuestion 关于影响范围，然后再继续。
• 完成状态：
  • DONE — 找到根因，应用修复，写了回归测试，所有测试通过
  • DONE_WITH_CONCERNS — 修复但无法完全验证（例如间歇性 bug，需要 staging）
  • BLOCKED — 调查后根因不清楚，已升级