菜单
遇到 bug、测试失败、构建失败、生产事故或异常行为时使用；在提出修复方案之前先找根因，不要凭直觉打补丁。 / Use for bugs, test failures, build failures, production incidents, or unexpected behavior — investigate the root cause before proposing a fix; do not patch symptoms.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use this skill when the task is specifically about AI search, AI Overviews, LLM citations, answer-engine optimization, or improving visibility in AI-generated answers. Good fit for AEO, GEO, LLMO, AI citations, zero-click AI visibility, and optimization for ChatGPT, Perplexity, Claude, Gemini, or similar systems. Do NOT use as the default for broad SEO audits or for pure schema implementation.
在创造性产品或设计工作之前使用此技能：创建新功能、构建新组件、添加新能力，或有意改变既定产品行为。在实现前先探索用户意图、需求和设计。不要用于 bug 修复、测试失败、构建失败、回归修复、恢复已有行为，或预期行为已经明确的实现任务；这些情况优先使用 systematic-debugging、test-driven-development 和 verification-before-completion。
Unified Impeccable frontend design skill. Use when the goal is to design, build, redesign, or improve a frontend interface — web pages, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, empty states, responsive behavior, typography, spacing, layout, color, motion, UX copy, accessibility, or UI-perceived performance. Also use for Impeccable command-style requests aimed at frontend work, such as `impeccable craft`, `shape`, `init`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live` (`teach` is only a deprecated alias for `init`). Do NOT use for backend or non-frontend code audits, docs, or reviews; live-site design-language extraction; static poster or cover art; HTML slide decks; PowerPoint / PDF / Word / spreadsheet deliverables; or specialized React/Next performance work.
在实现新功能、有意的行为变更，或非平凡 bug 修复时使用——先写一个会失败的测试，再写实现代码。例外：一次性原型、生成代码、配置文件、单行 trivial 修改、纯文案/排版/样式调整，以及没有可测行为的改动。 / Use when implementing new features, intentional behavior changes, or non-trivial bug fixes — write a failing test before implementation. Exceptions: throwaway prototypes, generated code, config files, trivial single-line patches, copy / typography / pure style edits, and changes with no testable behavior.
当确实需要与当前工作区隔离时使用，例如并行开发、临时 hotfix、PR 检查、多方案实验或执行大型实现计划。不要作为日常小修、普通 bug 修复、只读调查或单文件改动的默认流程。
在宣称工作完成、已修复或测试通过之前使用，在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功；始终用证据支撑断言。 / Use before claiming work is complete, fixed, or tests pass, and before commit / PR — run verification commands and confirm output before stating success; back every claim with evidence.
| name | systematic-debugging |
| description | 遇到 bug、测试失败、构建失败、生产事故或异常行为时使用；在提出修复方案之前先找根因，不要凭直觉打补丁。 / Use for bugs, test failures, build failures, production incidents, or unexpected behavior — investigate the root cause before proposing a fix; do not patch symptoms. |
| version | 1.0.0 |
| license | MIT |
| metadata | {"hermes":{"tags":["debugging"]}} |
随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查，不许提修复方案
如果你还没完成第一阶段，就不能提出修复方案。
用于任何技术问题：
尤其在以下情况必须使用：
以下情况也不要跳过：
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：
在提出修复方案之前，先添加诊断埋点：
对每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
执行一次以收集证据，确定断裂点在哪里
然后分析证据，定位故障组件
然后针对该组件深入调查
示例（多层系统）：
# 第 1 层：工作流
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# 第 2 层：构建脚本
echo "=== Env vars in build script: ==="
env | grep IDENTITY || 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 技能来编写规范的失败测试实施单一修复
验证修复
如果修复不起作用
如果 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 - 用条件轮询替代硬编码等待时间相关技能：
调试实践中的数据：