Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/docevilOck/agent-skills-hook --skill systematic-debuggingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| name | systematic-debugging |
| description | 在遇到任何 bug、测试失败或异常行为时使用，且要在提出修复之前使用 |
随手修补会浪费时间，还会引入新 bug。快速打补丁只会掩盖底层问题。
核心原则： 在尝试修复前，始终先找到根因。只修症状就是失败。
Violating the letter of this process is violating the spirit of debugging.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
如果你还没完成第 1 阶段，就不能开始提出修复方案。
适用于任何技术问题：
尤其在以下情况要用：
不要跳过的情况：
你必须先完成当前阶段，才能进入下一阶段。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查最近变更
在多组件系统中收集证据
当系统包含多个组件时（CI -> build -> signing，API -> service -> database）：
在提出修复之前，先加诊断埋点：
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Example (multi-layer system):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这会揭示： 是哪一层失败了（secrets -> workflow ✓，workflow -> build ✗）
追踪数据流
当错误出现在很深的调用栈里时：
See root-cause-tracing.md in this directory for the complete backward tracing technique.
简版：
先找模式，再修复：
找能工作的例子
对照参考实现
识别差异
理解依赖
科学方法：
提出单一假设
最小化测试
继续前先验证
不知道时
修根因，不修症状：
先创建能稳定复现问题的验证手段
Implement Single Fix
Verify Fix
If Fix Doesn't Work
If 3+ Fixes Failed: Question Architecture
Pattern indicating architectural problem:
STOP and question fundamentals:
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
如果你发现自己在想下面这些话：
以上任何一种情况都意味着：立刻停止，回到第 1 阶段。
如果已经失败了 3 次以上： 就要质疑架构（见第 4.5 步）
留意这些纠偏：
一旦听到这些信号： 立刻停止，回到第 1 阶段。
| 借口 | 现实 |
|---|---|
| “问题很简单，不需要流程” | 简单问题也有根因。对简单 bug 来说，流程反而更快。 |
| “这是紧急情况，没时间走流程” | 系统化调试比乱猜乱试更快。 |
| “先试这个，等会儿再调查” | 第一个修复会定下模式。开头就要做对。 |
| “先确认修复有效，再写测试” | 没测试的修复不稳。先测试才能证明。 |
| “一次改多个地方更省时间” | 没法分辨到底是哪一处起作用，还容易引入新 bug。 |
| “参考太长了，我按模式改一下就行” | 只懂一半，必然会出 bug。要完整读完。 |
| “我看到问题了，直接修就行” | 看到症状，不等于理解根因。 |
| “再试一次修复就好”（已经失败 2 次以上） | 失败 3 次以上说明是架构问题。该质疑模式，不该继续乱修。 |
| 阶段 | 关键动作 | 成功标准 |
|---|---|---|
| 1. 根因 | 看错误、复现、查变更、收集证据 | 明白是什么、为什么 |
| 2. 模式 | 找正常例子、对比 | 找出差异 |
| 3. 假设 | 提出理论、最小化测试 | 证实或产生新假设 |
| 4. 实现 | 创建测试、修复、验证 | bug 已解决，测试通过 |
如果系统化调查后发现，这个问题确实是环境相关、时序相关，或者来自外部：
但是： 95% 的“没有根因”案例，其实都是调查还不完整。
下面这些技巧是系统化调试的一部分，也都在这个目录里：
root-cause-tracing.md - Trace bugs backward through call stack to find original triggerdefense-in-depth.md - Add validation at multiple layers after finding root causecondition-based-waiting.md - Replace arbitrary timeouts with condition polling相关 skills：
来自调试实战：