Systematic debugging
Skill MARUCIE/openclaw-foundry/web/public/packs/algorithm-engineer/skills/algorithm/systematic-debugging
The curated AI Agent skill marketplace — 37K+ vetted skills, S/A/B/C ratings, deploy anywhere
npx -y skills add MARUCIE/openclaw-foundry --skill systematic-debuggingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when encountering a bug, test failure, crash, or unexpected behavior. Enforces root-cause investigation before any fix attempt. NOT for writing new features. Trigger: bug, error, failing test, broken, unexpected, crash, regression.
SKILL.md
3.5 KB, as published. Nobody here has run it
是什么
把"模型挂了 / 测试红了 / 线上崩了"的处理流程从"凭经验改改试试"升级成"先定位根因、再做最小修复"的 4 阶段纪律，帮你把"调试"从抓阄式打补丁变成可复用、可解释、可回溯的工程方法，避免补一个洞冒一个新洞。
怎么用
- 第一阶段先读完整错误堆栈、复现问题、对照最近改动、梳理数据流，让"为什么坏了"在动手前就有清晰假设。
- 第二阶段找历史上能跑通的版本、对比关键差异、理清依赖关系，让"坏的样子"和"好的样子"先并排看清。
- 第三阶段一次只验一个假设、用最小测试样例、控制单变量，让验证结果可解释不被多个改动污染。
- 第四阶段先写一个能复现 bug 的失败用例，再做单点修复，最后跑回归，让"修好了"有可验证证据而不是凭感觉。
- 触发 3-Strike Rule（三振规则）：连续 3 次修复都失败就停手，把问题升级为架构讨论，让团队不被表面 bug 拖入无尽补丁循环。
架构图
flowchart LR
A[问题出现] --> B[Phase 1 根因]
B --> C[Phase 2 模式对比]
C --> D[Phase 3 假设验证]
D --> E[Phase 4 修复 + 回归]
E --> F{3 次失败?}
F -->|是| G[升级架构讨论]
Systematic Debugging
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Gotchas
-
Don't propose fixes before Phase 1. The #1 failure mode is jumping to "quick fix" without understanding WHY. Symptom fixes mask root causes and create new bugs.
-
Multi-component systems need layer-by-layer evidence. Before guessing which component failed, inject diagnostics at EACH boundary:
# Layer 1: Entry point echo "=== Input data: ===" echo "VAR: ${VAR:+SET}${VAR:-UNSET}" # Layer 2: Processing echo "=== After transform: ===" # Layer 3: Output echo "=== Final state: ==="Run ONCE to see WHERE it breaks. Then investigate THAT layer only.
-
3-Strike Rule. Fix 1: diagnose & targeted fix. Fix 2: different approach. Fix 3: rethink assumptions. After 3 failed fixes: STOP — this is an architectural problem, not a bug. Discuss with user before attempting more.
4 Phases (Sequential, No Skipping)
Phase 1: Root Cause → Read errors fully, reproduce, check recent changes, trace data flow
Phase 2: Pattern → Find working examples, compare differences, understand dependencies
Phase 3: Hypothesis → Single hypothesis, smallest possible test, one variable at a time
Phase 4: Fix → Create failing test FIRST, implement single fix, verify, check for regressions
Red Flags — STOP and Return to Phase 1
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- Proposing solutions before tracing data flow
- "One more fix attempt" after 2+ failures
- Each fix reveals a new problem in a different place (= architectural issue)
Supporting References
root-cause-tracing.md— Backward tracing through call stackdefense-in-depth.md— Multi-layer validation after fixcondition-based-waiting.md— Replace timeouts with condition polling- Related:
verification-before-completion(verify fix before claiming success)