Menú
以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | yorz-debug |
| description | 以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。 |
指导 Agent 以资深工程师的调试纪律逐步逼近疑难 bug 的根因：不凭猜测改代码，坚持「假设 → 取证 → 验证 → 缩小范围 → 再假设」的证据闭环。调试过程赋予更大的自由度（临时改代码、Mock 数据、加日志、建临时验证入口），同时用 debug.md 活文档 + git stash create 快照兜住"污染性改动不进入最终提交"。
本 skill 不复用 yorz-spec 的 plan/tasks/execute 状态机。真相以
debug.md为单一载体；Agent 持续推进直至需要用户回传证据（人在环路），或根因确认并收尾。
debug.md 落点。fix 任务时勾选「Debug 模式」，后端 prompt 指向本 skill。status: debugging 的 debug.md（有未收尾记录块），run/append 路由自动切到本 skill。此时不新建记录块，定位活跃记录块（frontmatter active: NNN）续跑。spec_dir（可选）：spec 目录路径（含 spec.md）。给出时 debug.md 建在此目录，与 spec.md 同级。runId、name、cli、pid、startedAt、logFile 等字段。debug.md 落 spec_dir（与 spec.md 同级）。spec_dir 时，Debug 活文档必须落在项目临时目录 .yorz/tmp/debug/，文件名必须携带本地秒级时间信息，格式为 debug-YYYYMMDD-HHmmss.md；若 YorZ Service prompt 已给出具体文件路径，则以该路径为准。其余多记录模型、快照、脚手架、收尾流程与有 spec 时完全一致。一个 debug.md 承载同一 spec 生命周期内的多次调试（某次收尾后又发现新 bug，就追加下一条记录，不覆盖历史）。它同时是：调试活文档、Debug 模式的持久化标记（存在未收尾记录 = 处于 Debug 模式）、脚手架是否清理干净的守卫。
---
status: debugging # debugging（存在未收尾记录）| resolved（全部记录已收尾）
active: 2 # 当前活跃记录编号；resolved 时留空
updated_at: '2026-07-19 15:54:37' # 本地秒级字符串
---
每次进入 Debug 在文末追加一个记录块，编号 NNN 从 1 递增、不复用、不覆盖既有块：
## Debug 1 · <bug 一句话简述>
- 状态：debugging # debugging | resolved
- 快照：<git stash create 得到的 SHA>
- 进入时间：'2026-07-19 15:54:37'
### 1.1 Bug 现象与复现
...
### 1.2 关联链路分析
...
### 1.3 Debug 基线
快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。
### 1.4 假设看板
...
### 1.5 证据
...
### 1.6 脚手架清单
...
### 1.7 收尾核对
...
debug.md 不存在则创建（写文件 frontmatter + 第 1 个记录块）；已存在则追加 ## Debug <max+1>，置文件 status: debugging、active: <新编号>。进入后立刻打快照（见「污染防线」）。状态 置 resolved，脚手架逐条核销，git diff <SNAP> 校验只剩合法修复。resolved，置文件 status: resolved、清空 active；否则保持 debugging 且 active 指向仍在调试的块。debug.md 供复盘，绝不删除。分析 → 规划 → 假设 → 实施 → 验证 → 缩小范围 → 再假设，直至根因被硬证据锁定。
flowchart TD
Start["接手 bug"] --> Repro{"能稳定复现?"}
Repro -->|否| GetRepro["补齐复现步骤<br/>（问用户 / 自行构造）"]
GetRepro --> Repro
Repro -->|是| Analyze["分析关联链路<br/>写入 debug.md"]
Analyze --> Hypo["提出可证伪假设<br/>成立看到 X / 不成立看到 Y"]
Hypo --> Probe["写验证性代码 / 加日志<br/>登记脚手架清单"]
Probe --> Eval{"证据指向?"}
Eval -->|证伪| Exclude["记入已排除假设 + 依据"]
Exclude --> Narrow["缩小范围（二分/控制变量）"]
Narrow --> Hypo
Eval -->|坐实根因| Fix["写最终修复"]
Fix --> Verify{"重跑复现步骤<br/>问题消失?"}
Verify -->|否| Hypo
Verify -->|是| Close["进入收尾"]
JSON.stringify(x)），避免直接打印对象或复杂结构变量的引用。每一处临时改动都必须在「脚手架清单」登记一行（文件 + 位置 + 类型：短路 / Mock / 注释 / 临时页面 / 临时日志），收尾逐条核销。未登记 = 会漏还原。
在当前项目与分支就地调试，不开 worktree；靠快照 + 脚手架清单 + diff 兜住污染。
flowchart TD
Enter["进入 Debug（新记录块）"] --> Snap["SNAP = git stash create<br/>零副作用快照当前脏工作区"]
Snap --> Record["把 SNAP 写入记录块 · Debug 基线"]
Record --> Loop["调试循环<br/>照常改代码 + 登记脚手架清单"]
Loop --> Fixed{"根因确认 + 硬证据?"}
Fixed -->|否| Loop
Fixed -->|是| Revert["按脚手架清单逐条还原"]
Revert --> Diff["git diff SNAP"]
Diff --> Gate{"仅剩合法修复?"}
Gate -->|否| Revert
Gate -->|是| Done["置本块 status: resolved<br/>跑变更文件单测/build/typecheck"]
git stash create（不是 git stash / 临时 commit）生成一个记录当前脏工作区的 commit 对象，但不动工作区 / index / HEAD。它天然区分"进入前的既有未提交改动"与"调试引入的改动"，避免临时 commit 的还原风险。把返回的 SHA 写入记录块「Debug 基线」。
git stash create 无输出（工作区干净），以当前 HEAD（git rev-parse HEAD）作为快照基准并注明。git diff <SNAP> 必须只剩合法修复——所有短路 / Mock / 注释 / 临时页面 / 临时日志都已还原。diff 里还有脚手架残留 = 不许收尾。根因确认且修复通过复现验证后：
git diff <SNAP> 只剩合法修复（脚手架清单全部核销）。状态 置 resolved；按「文件 status 收敛」更新文件 frontmatter（全部 resolved → 文件 status: resolved、清空 active）。debug.md 保留，供复盘。收尾后如又发现新 bug，回到本 skill 追加下一条
## Debug NNN记录块（不覆盖历史），重新走一遍循环。
debug.md 都更新文件 frontmatter 的 updated_at。updated_at 用本地秒级 YYYY-MM-DD HH:mm:ss 字符串。