Investigate bugs, failing tests, and unexpected behavior through reproducible steps, logs, and comparisons with working code. Follow four stages to identify the root cause, test a hypothesis, apply a focused fix, and verify the result.
中文简介正在准备中。当前显示英语简介。
遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
安装前可以查看交给 AI 代理的指令内容。
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查，不许提修复方案
如果你还没完成第一阶段，就不能提出修复方案。
用于任何技术问题：
尤其在以下情况必须使用：
以下情况也不要跳过：
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：
在提出修复方案之前，先添加诊断埋点：
对每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
执行一次以收集证据，确定断裂点在哪里
然后分析证据，定位故障组件
然后针对该组件深入调查
示例（多层系统）：
# 第 1 层：工作流
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
# 第 2 层：构建脚本
echo "=== Env vars in build script: ==="
printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
# 第 3 层：签名脚本
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# 第 4 层：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"
由此可以看出： 哪一层出了问题（secrets → workflow ✓, workflow → build ✗）
跟踪数据流
当错误发生在调用栈深处时：
参见本目录下的 root-cause-tracing.md，了解完整的反向追踪技术。
简要版本：
先找到模式，再修复：
找到可正常工作的示例
与参考实现对比
识别差异
理解依赖关系
科学方法：
提出单一假设
最小化测试
继续之前先验证
当你不确定时
修复根本原因，而非症状：
创建失败的测试用例
test-driven-development 技能来编写规范的失败测试实施单一修复
验证修复
verification-before-completion 技能如果修复不起作用
如果 3 次以上修复都失败了：质疑架构
以下模式表明存在架构问题：
停下来质疑根本性问题：
在尝试更多修复之前，和你的搭档讨论
这不是假设失败——这是架构有误。
如果你发现自己在想：
以上这些都意味着：停下来。回到第一阶段。
如果 3 次以上修复都失败了： 质疑架构（见第四阶段第 5 步）
留意这些提醒：
当你看到这些信号时： 停下来。回到第一阶段。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要走流程" | 简单问题也有根本原因。对于简单 bug，流程很快就能走完。 |
| "紧急情况，没时间走流程" | 系统化调试比反复猜测式修复更快。 |
| "先试一下，再排查" | 第一次修复就定下了基调。从一开始就做对。 |
| "确认修复有效后再写测试" | 没有测试的修复留不住。先写测试才能证明修复有效。 |
| "一次修多个问题省时间" | 无法隔离哪个生效了。还会引入新 bug。 |
| "参考实现太长了，我自己改改" | 一知半解必然出 bug。完整阅读。 |
| "我看出问题了，让我修一下" | 看到症状 ≠ 理解根因。 |
| "再试一次"（在 2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要继续修。 |
| 阶段 | 关键活动 | 通过标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查变更、收集证据 | 理解了什么出了问题以及为什么 |
| 2. 模式 | 找到正常示例、对比 | 识别出差异 |
| 3. 假设 | 提出理论、最小化验证 | 假设被验证或产生新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 已修复，测试通过 |
如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的：
但是： 95% 的"找不到根因"其实是排查不充分。
以下技术是系统化调试的组成部分，可在本目录中找到：
root-cause-tracing.md - 沿调用栈反向追踪 bug，找到最初的触发点defense-in-depth.md - 找到根因后，在多个层级添加校验condition-based-waiting.md - 用条件轮询替代硬编码等待时间还没有评价。欢迎分享你的使用感受。
无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。
还没有评论。来写第一条吧。
Turn development ideas into agreed designs through focused conversation. The skill clarifies goals, constraints, and success criteria, then chooses a process for feasibility research, small changes, or new systems before implementation begins.
中文简介正在准备中。当前显示英语简介。
Write Chinese code review feedback that clearly distinguishes required fixes, suggestions, and optional advice. Use question and suggestion templates, organize review summaries, and follow guidance for mixed Chinese-English comments and commit messages.
中文简介正在准备中。当前显示英语简介。
Standardize Chinese Git commit messages and changelogs using Conventional Commits, a structured message format. The skill provides writing rules and configuration examples for message checks, interactive commit entry, and automatic changelog generation.
中文简介正在准备中。当前显示英语简介。
Write and revise Chinese technical documentation using consistent spacing, punctuation, terminology, and structure. Includes README.md and API documentation templates, bilingual formatting examples, and a checklist for reviewing documents before publication.
中文简介正在准备中。当前显示英语简介。
Set up Git workflows for Gitee, Coding.net, 极狐 GitLab, and CNB with platform-specific connection and authentication examples. Choose branching rules, standardize Chinese commit messages, and adapt automated testing and deployment configurations to your team's workflow.
中文简介正在准备中。当前显示英语简介。
Review AI agent session logs to document repeated work, departures from plans, delays, and token usage. Produce an evidence-based report with file and line references, and prepare a bug report when appropriate.
中文简介正在准备中。当前显示英语简介。