调查

工程开发 社区

技能解读

设计思路

gstack-openclaw-investigate 是 gstack 的「root cause 调查 SOP」——五个阶段,从根因追查到回归测试到结构化报告,每一步都有硬规则。Iron Law:3 次失败的修复尝试 → 停下来质疑架构(错的是结构,不是单点假设)。

五阶段

Phase 1:Root Cause Investigation 追到根因,不停在症状层。

Phase 2:Pattern Analysis 看是不是已知模式 / 既往同类 bug。

Phase 3:Hypothesis Testing 列假设、按可能性排序、逐个验证。3 个假设跑完都不中就停下:

"3 hypotheses tested, none match. This may be an architectural issue rather than a simple bug."

给用户三个选项:继续投新假设(描述清楚)/ escalate 给懂系统的人 / 加 logging 等下次复现。

Red flags(看到放慢节奏):

  • "Quick fix for now"——没有「for now」,要么修对要么 escalate
  • 没追数据流就开始提 fix——你在猜
  • 每修一处就在别处冒新问题——错层不是错码

Phase 4:Implementation

  • Fix root cause, not symptom——最小改动消除真问题
  • Minimal diff——动文件最少、行最少;忍住别顺手重构
  • 写回归测试:fix 之前 fail(证明测试有意义)、fix 之后 pass(证明 fix 有效)
  • 跑全套测试——零回归
  • fix 改 > 5 文件:先报 blast radius 给用户再继续——bug fix 改这么多算大动作

Phase 5:Verification & Report

  • Fresh verification:复现原 bug 场景验证已修——非可选
  • 跑全套测试
  • 输出结构化 DEBUG REPORT:
    • Symptom / Root cause / Fix(含文件引用) / Evidence(测试输出 + 复现) / Regression test 位置 / Related(同区域往例 / 架构注记) / Status
  • 存到 memory/ 加日期戳

Status 取值

  • DONE:根因找到、fix 应用、回归测试写完、全套通过
  • DONE_WITH_CONCERNS:修了但无法完整验证(间歇 bug、需要 staging)
  • BLOCKED:调查后根因仍不清,已 escalate

重要规则

  • 3+ failed fix attempts: STOP and question the architecture.
  • Never apply a fix you cannot verify.
  • Never say "this should fix it"——验证给我看,跑测试。
  • Fix 改 > 5 文件:先报 blast radius。

适合谁

  • 调查复杂 / 跨模块 bug 的工程师
  • 想把调试经验产品化、给团队留报告的 Tech Lead
  • 反复出现的疑难 bug 想做根因调查

不适合

  • 一眼看穿的低级错误——直接改
  • 不在 gstack 生态——diagnose 是更轻量的等价物

配套

diagnose(superpowers 等价物)、improve-codebase-architecture(3+ fail 后的下一站)、systematic-debugging(更基础的调试方法论)。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@garrytan · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

01
第一阶段:根本原因调查

在形成任何假设之前收集背景信息。收集症状:阅读错误消息、堆栈跟踪和重现步骤。如果用户没有提供足够的上下文,请一次问一个问题。不要一次问五个问题。阅读代码:跟踪从症状到潜在原因的代码路径。搜索所有参考资料,阅读故障点周围的逻辑。检查最近的更改:

02
第二阶段:模式分析

检查此错误是否与已知模式匹配:竞争条件...间歇性的,与时间相关的。查看对共享状态的并发访问。 Nil/null 传播...NoMethodError、TypeError。可选值缺少防护。状态损坏......数据不一致,部分更新。检查事务、回调、挂钩。集成失败...超时,意外响应。外部API调用、服务边界。

03
第三阶段:假设检验

在编写任何修复程序之前,请验证您的假设。确认假设:在可疑的根本原因处添加临时日志语句、断言或调试输出。运行复制。证据相符吗?如果假设错误:搜索错误(首先清理敏感数据)。返回第一阶段。收集更多证据。不要猜测。 3 次打击规则:如果 3 个假设失败,则停止。告诉用户:

04
第四阶段:实施

确认根本原因后:解决根本原因,而不是症状。消除实际问题的最小改变。最小差异:接触的文件最少,更改的行最少。抵制重构相邻代码的冲动。编写一个回归测试: 如果没有修复就会失败(证明测试是有意义的)

05
第五阶段:验证和报告

全新验证:重现原始错误场景并确认其已修复。这不是可选的。运行测试套件。输出结构化调试报告:DEBUG REPORT 症状:用户观察到的内容

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。