关于 gstack-openclaw-investigate
gstack-openclaw-investigate 是面向开发者和编码 Agent 的系统化调试技能。它要求先查明并验证根因，再实施最小修复，并验证结果、保存报告。
主要功能
- 01追踪症状与近期变更
- 02检验根因假设
- 03三次假设失败后停止
- 04添加回归测试
- 05验证修复并保存报告
适用场景
- 01调查可复现的软件故障
- 02从近期变更追查回归问题
- 03记录已验证的修复供后续参考
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/gstack-openclaw-investigate确认已加载。
详细介绍
系统化调试
铁律
未先调查根本原因，不得进行任何修复。
修复症状会导致打地鼠式调试。每次未解决根本原因的修复，都会让下一个 Bug 更难排查。找到根本原因，然后修复它。
阶段 1：调查根本原因
形成任何假设之前，先收集背景信息。
-
收集症状： 阅读错误消息、堆栈跟踪和复现步骤。如果用户提供的背景信息不足，每次只问一个问题。不要一次问五个问题。
-
阅读代码： 从症状出发，沿代码路径追溯潜在原因。搜索所有引用，并阅读故障点附近的逻辑。
-
检查近期变更：
git log --oneline -20 -- <affected-files>之前能正常工作吗？发生了什么变化？如果是回归问题，根本原因就在差异中。
-
复现问题： 能否稳定触发这个 Bug？如果不能，在继续之前收集更多证据。
-
检查记忆中是否有同一方面以往的调试记录。同一文件反复出现 Bug，说明架构存在问题。
输出：“根本原因假设：……”……具体、可测试地说明哪里出了问题以及原因。
阶段 2：模式分析
检查这个 Bug 是否符合已知模式：
竞态条件……间歇性发生，依赖时序。检查对共享状态的并发访问。
Nil/null 传播……NoMethodError、TypeError。对可选值缺少保护。
状态损坏……数据不一致、部分更新。检查事务、回调和钩子。
集成故障……超时、响应异常。检查外部 API 调用和服务边界。
配置漂移……本地运行正常，但在 staging/prod 中失败。检查环境变量、功能标志和数据库状态。
缓存过期……显示旧数据，清除缓存后恢复。检查 Redis、CDN 和浏览器缓存。
另外还要检查：
- 项目中是否有相关问题的已知记录
- 同一方面以往修复的 Git 日志。同一文件反复出现 Bug，说明架构存在问题，并非巧合。
外部搜索： 如果 Bug 不符合已知模式，请在线搜索错误类型。先清理信息： 去除主机名、IP、文件路径、SQL 和客户数据。搜索错误类别，不要搜索原始消息。
阶段 3：测试假设
编写任何修复代码之前，先验证你的假设。
-
确认假设： 在疑似根本原因处添加临时日志语句、断言或调试输出。运行复现步骤。证据是否吻合？
-
如果假设不成立： 搜索该错误（先清理敏感数据）。返回阶段 1，收集更多证据。不要猜测。
-
三次失败规则： 如果 3 个假设都不成立，停止。告诉用户：
“已测试 3 个假设，均不吻合。这可能是架构问题，而非简单 Bug。”
可选方案：
- 使用新假设继续调查（说明该假设）
- 升级处理，交由人工审查（需要熟悉该系统的人）
- 添加日志并等待（为相关区域添加埋点，下次捕获问题）
危险信号……如果出现以下情况，请放慢速度：
- “先快速修一下”……没有所谓的“先”。要么正确修复，要么升级处理。
- 尚未追踪数据流就提出修复方案……这是在猜测。
- 每次修复都在其他地方引出新问题……问题出在错误的层，而非错误的代码。
阶段 4：实施
确认根本原因后：
-
修复根本原因，而非症状。 用最小的改动消除实际问题。
-
尽量减少差异： 触及的文件最少，改动的行数最少。克制重构相邻代码的冲动。
-
编写回归测试，确保：
- 不应用修复时失败（证明测试有意义）
- 应用修复后通过（证明修复有效）
-
运行完整测试套件。 不允许引入回归问题。
-
如果修复涉及 >5 个文件： 在继续之前，向用户说明影响范围。对于 Bug 修复而言，这个范围很大。
阶段 5：验证与报告
全新验证： 重现原始错误场景，并确认问题已修复。这是必做项。
运行测试套件。
输出一份结构化调试报告：
调试报告
- 症状： 用户观察到的现象
- 根本原因： 实际问题所在
- 修复： 所做的更改及文件引用
- 证据： 测试输出、证明修复有效的复现过程
- 回归测试： 新测试的位置
- 相关信息： 同一领域的既往错误、架构说明
- 状态： DONE | DONE_WITH_CONCERNS | BLOCKED
将报告保存到 memory/，并使用当天日期命名，以便后续会话参考。
重要规则
- 修复尝试失败 3 次以上：停止并质疑架构。 这不是假设失败，而是架构有误。
- 绝不要应用无法验证的修复。 如果无法复现并确认，就不要发布。
- 绝不要说“这应该能修复问题”。 必须验证并证明修复有效。运行测试。
- 如果修复涉及超过 5 个文件： 继续之前先告知用户。
- 完成状态：
- DONE ……已找到根本原因、应用修复、编写回归测试，且所有测试均通过
- DONE_WITH_CONCERNS ……已修复，但无法完全验证（例如，间歇性错误、需要在预发布环境中验证）
- BLOCKED ……调查后仍不清楚根本原因，已升级处理