菜单
Use when user says 'diagnose this' / 'debug this' / '怎么定位' / 'reproduce 不出来', or reports a bug that throws/fails, or describes a perf regression. 产出根因 + 推荐修复方案,不直接写修复代码。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | diagnose |
| description | Use when user says 'diagnose this' / 'debug this' / '怎么定位' / 'reproduce 不出来', or reports a bug that throws/fails, or describes a perf regression. 产出根因 + 推荐修复方案,不直接写修复代码。 |
| argument-hint | <bug/症状描述> |
硬 bug 的纪律。只有明确理由才能跳 Phase,默认按序走。
术语用 core/specs/shared/glossary.md;架构讨论用 core/specs/shared/architecture-language.md。
这是本 skill 的全部精华。剩下都是机械动作。如果你有一个快速、确定、agent 可跑的 pass/fail 信号指向这个 bug,你会找到根因——二分、假设证伪、instrumentation 都只是消费那个信号。没有信号,盯代码再久也救不了你。
在这一步花超常比例的精力。主动、创造性、拒绝放弃。
git bisect run 驱动scripts/hitl-loop.template.sh 把人变成循环的一环建好对的反馈循环,bug 就修了 90%。
有了 一个 循环后问:
30 秒且 flaky 的循环只比没循环好一点点。2 秒且确定的循环是 debugging 超能力。
目标不是干净复现,是提高复现率。loop trigger 100 次 / 并行 / 加压力 / 收窄时序窗口 / 注入 sleep。50% flake 的 bug 可调,1% 不可——把复现率往上推到可调。
停下来明说。列出你试过什么。问用户要:(a) 能复现的环境访问权限,(b) 抓到的工件(HAR / log dump / core dump / 带时间戳的录屏),或 (c) 在生产加临时 instrumentation 的授权。不要没循环就进 Phase 2 猜。
建好你相信的循环,再进 Phase 2。
跑循环。看 bug 出来。
确认:
复现不出来不进 Phase 3。
在验证任何假设前生成 3-5 个 ranked 假设。单假设容易锚定在第一个看起来合理的想法上。
每个假设必须可证伪:
格式:"If 是因,then <改 Y> 会让 bug 消失 / <改 Z> 会让 bug 加重。"
写不出预测 → vibe,弃之。
| Rank | 假设 | 预测(If…then…) | 证伪成本 |
|---|---|---|---|
| 1 | … | If X then Y | 低 / 中 / 高 |
| 2 | … | … | … |
把 ranked list 发给用户再开始证伪。用户的领域知识经常能瞬间重排("我们刚给 #3 改了 deploy"),或说出已经排除的假设。不要 block 等用户;用户 AFK 就按你的排名进。不调 AskUserQuestion,只是自然语言展示 + 邀请 "如需调整告诉我,否则我按 rank 顺序开始证伪"。
假设证伪迭代到 第 2 轮仍不收敛（全部 ranked 假设证伪、无新的可证伪假设可生成、或新假设仍解释不了观察到的症状）→ 标 stuck_or_looping，由主会话按 core/specs/shared/codex-routing.md § Decision Table 调 collaborating-with-codex --oracle-review：把已证伪假设清单 + 反馈循环 + 观察到的症状作为 context 喂给 oracle 拿 alternative POV，回 Phase 3 重排假设。调用 contract 见 codex-routing.md § Invocation Contract（TASK / CONTEXT / FILES / RISK_SIGNALS / NON_GOALS 必填）。Codex 不可用 → 主会话兜底重排，Phase 5 输出 oracle_status: codex_degraded + 一句话降级原因。Codex 调用不阻断 Phase 推进。
每个 probe 对应 Phase 3 的一个具体预测。一次只改一个变量。
工具偏好:
每条 debug log 加独特前缀(如 [DEBUG-a4f2])。结束时一个 grep 就能清掉。无 tag 的 log 存活,有 tag 的 log 死掉。
性能分支:perf regression 时 log 常常是错的。改用:建 baseline 测量(timing harness / performance.now() / profiler / query plan)→ 二分。先测,再修。
到这里 diagnose 就结束。产出:
- root_cause: <一句话 + 证据指针>
- falsified_hypotheses: [<哪些被证伪及为什么>]
- recommended_fix: <方案描述 + 影响边界>
- alternative_fixes: [<备选>]
- repro_loop: <Phase 1 最终用的循环>
- regression_seam: <有没有合适的 seam 放回归测试,没有则说明>
- oracle_consulted: <true | false> # Phase 3 stuck 是否触发过 codex oracle
- oracle_status: <ok | codex_degraded | skipped> # consulted 时 ok / codex 不可用 codex_degraded / 未触发 skipped
- oracle_insight: <若 consulted=true 且 status=ok,oracle 给的关键 POV 摘要;degraded 时填降级原因;否则省略>
不写修复代码。交给:
/fix-bug 消费(做 Phase 2 确认 + Phase 3 修复 + Phase 4 review)/workflow-execute 消费(如果在 workflow 里)产出给下游前完成:
[DEBUG-...] instrumentation 移除(grep 前缀)stuck_or_looping,应当调 codex oracle 拿 alternative POV,不要继续闭门循环fix-bug Phase 1 开头会建议先 /diagnose 建反馈循环bug-batch 内部修复协议不进入本 skill,用自己的批量分析/workflow-spec 或 improve-codebase-architecture 思路Use when 用户调用 /design-plan, or 需要为复杂跨服务需求(多服务改动 / 数据库 DDL / 新增对外接口 / 架构调整)产出可评审的技术方案文档,典型用户是技术主管 / 资深研发。简单单服务改动走 /workflow-spec,Bug 修复走 /fix-bug。
Use when asked to review a diff, do a pre-commit code review, or review staged/branch changes. Supports staged diffs, branch diffs, and session mode that reviews only files edited in the current conversation context.
Use when 用户调用 /plan-archive, or 三阶段研发流程的阶段三:在所有模块研发上线后,根据实际代码改动回写阶段一技术方案 + 项目级架构文档(docs/architecture / docs/contracts / docs/assets/概要设计 等)。
Use when 用户说「快速规划」「轻规划」「不走 workflow」「plan 一下」「quick plan」, or 需求清晰、作用域明确、可一次性规划完成的简单到中等任务。复杂项目(跨 module / 新子系统 / 需追溯)或需要正式需求文档 / PRD 请用 /workflow-spec。
Use when 用户调用 /spec-bootstrap, or 项目尚未建立 .claude/code-specs/ 骨架且需要初始化 code-specs 体系。
Use when 用户调用 /spec-update, or 工作中沉淀出新 convention / 接口 contract / 模式需要落到 .claude/code-specs/, or execute 末尾终审（workflow-execute Step 7）建议沉淀 code-spec。