Menu
当遇到任何 bug、测试失败或意外行为时，在提出修复之前必须使用
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.
Based on SOC occupation classification
Update Kimi Code CLI user documentation after meaningful code changes that affect product behavior or user experience.
Map systematic debugging onto Ganymede Code native Debug / 排障 surfaces (probes, user verification bar, TodoList).
Map KimiCodeBoost engineering workflows onto Ganymede Code native UI and host tools (AskUserQuestion, TodoList, Agent, Plans panel, GanymedeBrowser, Worktree, Review).
在开展任何创造性工作之前必须使用：创建功能、构建组件、添加能力或修改行为。在动手实现前，先探索用户意图、需求并制定设计。
当同时面对 2 个及以上相互独立、无共享状态且无顺序依赖的任务时必须使用本技能
当需要在一个独立会话中执行已撰写的实现计划，并通过检查点进行复核时必须使用
| name | systematic-debugging |
| description | 当遇到任何 bug、测试失败或意外行为时，在提出修复之前必须使用 |
随机修复只会浪费时间并引入新 bug。临时补丁会掩盖根本问题。
核心原则： 必须先找到根本原因，再尝试修复。只修症状就是失败。
违背流程的字面要求，就是违背调试的精神。
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
如果尚未完成第一阶段，就不能提出修复方案。
适用于任何技术问题：
尤其在以下情况下使用：
不要跳过此流程的情况：
必须按顺序完成每个阶段，然后才能进入下一阶段。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现问题
检查近期变更
在 multi-component 系统中收集证据
当系统包含多个组件时（CI → build → signing、API → service → database）：
在提出修复方案之前，先添加诊断埋点：
对于每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置传递
- 检查每一层的状态
运行一次以收集证据，定位故障位置
然后分析证据，确定具体失效的组件
再针对该组件深入调查
示例（多层系统）：
# 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 ✗）
追踪数据流
当错误出现在调用栈深处时：
请参阅本目录中的 root-cause-tracing.md，了解完整的反向追踪技术。
快速版本：
在修复之前先找到模式：
寻找可运行的示例
与参考实现对比
识别差异
理解依赖关系
使用科学方法：
形成单一假设
最小化验证
验证后再继续
当你不确定时
修复根本原因，而不是症状：
创建失败的测试用例
test-driven-development skill实施单一修复
验证修复
如果修复无效
如果 3 次以上修复失败：质疑架构
表明存在架构问题的迹象：
停下来并质疑根本问题：
在尝试更多修复之前，先与人类伙伴讨论
这不是假设失败，而是架构错误。
如果你发现自己这样想：
以上任何一条都意味着：停下来，回到第一阶段。
如果 3 次以上修复失败： 质疑架构（见第四阶段第 5 步）
注意这些引导语：
当你看到这些信号时： 停下来，回到第一阶段。
| 借口 | 事实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 同样快速。 |
| "情况紧急，没时间按流程" | 系统性调试比猜测式试错更快。 |
| "先试一下这个，不行再调查" | 第一次修复就会定下调子。从一开始就要做对。 |
| "等确认修复有效后再写测试" | 未经测试的修复无法保持。先写测试才能证明问题。 |
| "一次性改多处更省时间" | 无法隔离真正起作用的改动，还会引入新 bug。 |
| "参考太长，我按理解适配一下" | 一知半解必然导致 bug。必须完整阅读。 |
| "我看到问题了，我来修" | 看到症状 ≠ 理解根本原因。 |
| "再试一次修复"（已失败 2 次以上） | 3 次以上失败 = 架构问题。要质疑模式，而不是继续修。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根本原因 | 阅读错误、复现、检查变更、收集证据 | 理解 WHAT 和 WHY |
| 2. 模式分析 | 寻找可运行示例、对比 | 识别差异 |
| 3. 假设验证 | 形成理论、最小化验证 | 假设被证实或提出新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 解决、测试通过 |
如果系统调查显示问题确实是环境相关、时序相关或外部因素：
但是： 95% 的"没有根本原因"都是调查不完整。
这些技术是系统性调试的一部分，本目录下均有相关文件：
root-cause-tracing.md - 从调用栈反向追踪 bug，找到原始触发点defense-in-depth.md - 找到根本原因后，在多层添加校验condition-based-waiting.md - 用条件轮询替代任意超时相关 skill：
来自真实调试会话的数据：