调查
- 作者仓库星标 0
- 作者更新于 2026年8月24日 15:55
- 作者仓库 gstack
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @garrytan · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第一阶段:根本原因调查
在形成任何假设之前收集背景信息。收集症状:阅读错误消息、堆栈跟踪和重现步骤。如果用户没有提供足够的上下文,请一次问一个问题。不要一次问五个问题。阅读代码:跟踪从症状到潜在原因的代码路径。搜索所有参考资料,阅读故障点周围的逻辑。检查最近的更改:
第二阶段:模式分析
检查此错误是否与已知模式匹配:竞争条件...间歇性的,与时间相关的。查看对共享状态的并发访问。 Nil/null 传播...NoMethodError、TypeError。可选值缺少防护。状态损坏......数据不一致,部分更新。检查事务、回调、挂钩。集成失败...超时,意外响应。外部API调用、服务边界。
第三阶段:假设检验
在编写任何修复程序之前,请验证您的假设。确认假设:在可疑的根本原因处添加临时日志语句、断言或调试输出。运行复制。证据相符吗?如果假设错误:搜索错误(首先清理敏感数据)。返回第一阶段。收集更多证据。不要猜测。 3 次打击规则:如果 3 个假设失败,则停止。告诉用户:
第四阶段:实施
确认根本原因后:解决根本原因,而不是症状。消除实际问题的最小改变。最小差异:接触的文件最少,更改的行最少。抵制重构相邻代码的冲动。编写一个回归测试: 如果没有修复就会失败(证明测试是有意义的)
第五阶段:验证和报告
全新验证:重现原始错误场景并确认其已修复。这不是可选的。运行测试套件。输出结构化调试报告:DEBUG REPORT 症状:用户观察到的内容
# Systematic Debugging
## Iron Law
**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it.
---
## Phase 1: Root Cause Investigation
Gather context before forming any hypothesis.
1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time. Don't ask five questions at once.
2. **Read the code:** Trace the code path from the symptom back to potential causes. Search for all references, read the logic around the failure point.
3. **Check recent changes:**
```bash
git log --oneline -20 -- <affected-files>
```
Was this working before? What changed? A regression means the root cause is in the diff.
4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.
5. **Check memory** for prior debugging sessions on the same area. Recurring bugs in the same files are an architectural smell.
Output: **"Root cause hypothesis: ..."** ... a specific, testable claim about what is wrong and why.
---
## Phase 2: Pattern Analysis
Check if this bug matches a known pattern:
**Race condition** ... Intermittent, timing-dependent. Look at concurrent access to shared state.
**Nil/null propagation** ... NoMethodError, TypeError. Missing guards on optional values.
**State corruption** ... Inconsistent data, partial updates. Check transactions, callbacks, hooks.
**Integration failure** ... Timeout, unexpected response. External API calls, service boundaries.
**Configuration drift** ... Works locally, fails in staging/prod. Env vars, feature flags, DB state.
**Stale cache** ... Shows old data, fixes on cache clear. Redis, CDN, browser cache.
Also check:
- Known issues in the project for related problems
- Git log for prior fixes in the same area. Recurring bugs in the same files are an architectural smell, not a coincidence.
**External search:** If the bug doesn't match a known pattern, search for the error type online. **Sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.
---
## Phase 3: Hypothesis Testing
Before writing ANY fix, verify your hypothesis.
1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?
2. **If the hypothesis is wrong:** Search for the error (sanitize sensitive data first). Return to Phase 1. Gather more evidence. Do not guess.
3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Tell the user:
"3 hypotheses tested, none match. This may be an architectural issue rather than a simple bug."
Options:
- Continue investigating with a new hypothesis (describe it)
- Escalate for human review (needs someone who knows the system)
- Add logging and wait (instrument the area and catch it next time)
**Red flags** ... if you see any of these, slow down:
- "Quick fix for now" ... there is no "for now." Fix it right or escalate.
- Proposing a fix before tracing data flow ... you're guessing.
- Each fix reveals a new problem elsewhere ... wrong layer, not wrong code.
---
## Phase 4: Implementation
Once root cause is confirmed:
1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem.
2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code.
3. **Write a regression test** that:
- **Fails** without the fix (proves the test is meaningful)
- **Passes** with the fix (proves the fix works)
4. **Run the full test suite.** No regressions allowed.
5. **If the fix touches >5 files:** Flag the blast radius to the user before proceeding. That's large for a bug fix.
---
## Phase 5: Verification & Report
**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional.
Run the test suite.
Output a structured debug report:
**DEBUG REPORT**
- **Symptom:** what the user observed
- **Root cause:** what was actually wrong
- **Fix:** what was changed, with file references
- **Evidence:** test output, reproduction showing fix works
- **Regression test:** location of the new test
- **Related:** prior bugs in same area, architectural notes
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED
Save the report to `memory/` with today's date so future sessions can reference it.
---
## Important Rules
- **3+ failed fix attempts: STOP and question the architecture.** Wrong architecture, not failed hypothesis.
- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it.
- **Never say "this should fix it."** Verify and prove it. Run the tests.
- **If fix touches >5 files:** Flag to user before proceeding.
- **Completion status:**
- DONE ... root cause found, fix applied, regression test written, all tests pass
- DONE_WITH_CONCERNS ... fixed but cannot fully verify (e.g., intermittent bug, requires staging)
- BLOCKED ... root cause unclear after investigation, escalated
章节与文件索引
按说明文件中的顺序排列。
铁律
第一阶段:根本原因调查
第二阶段:模式分析
第三阶段:假设检验
第四阶段:实施
文件/命令 -> memory/ · Nil/null · staging/prod.
内容校验值 -> 5a5317c09344
设计思路
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 个假设跑完都不中就停下:
给用户三个选项:继续投新假设(描述清楚)/ escalate 给懂系统的人 / 加 logging 等下次复现。
Red flags(看到放慢节奏):
Phase 4:Implementation
Phase 5:Verification & Report
memory/加日期戳Status 取值
重要规则
适合谁
不适合
diagnose是更轻量的等价物配套
diagnose(superpowers 等价物)、improve-codebase-architecture(3+ fail 后的下一站)、systematic-debugging(更基础的调试方法论)。