| name | trellis-debug-systematic-zh |
| description | 当 Trellis 子任务实现/验证过程中测试该绿不绿、或自检命令失败时，用一段不可偏离的刚性脚本做系统化根因定位与最小修复。用于 Codex / Claude Code 等驱动 qwen3.6 35b 这类小参数模型调试时——小模型一旦自由发挥就会到处乱改，本技能用"一次只改一处、改完必重跑、禁止猜"的铁律把它锁在窄路径上，并带防御性回归检查。
|
Trellis 系统化调试（刚性脚本）
概览
接管一次失败的测试或自检命令，按固定的 4 步把它修绿：固定失败信号 → 定位 → 单一假设验证 → 最小修复 + 回归。本技能存在的意义是防止（尤其是小模型）在调试时乱改、越改越坏——所以它是一段编号脚本 + 铁律，不是建议。
触发：trellis-implement-tdd-zh 的红绿循环里某测试该绿不绿，或 prd.md 自检命令失败，且原因不显然。
调试轨迹固定写入任务目录下的 <task-dir>/debug-report.md。第一次进入调试时从 references/debug-report-template.md 创建，后续每次新的调试事件在同一个文件里追加一个 session 块；不要改 skill 目录里的模板文件。
约束（铁律）
- 一次只改一处。改完立刻重跑那个失败命令，再决定下一步。
- 改完必重跑原失败命令。不重跑就不算验证。
- 禁止猜。定位只用"读栈 / 二分注释 / 加一行日志"三招缩小范围，不靠想象改代码。
- 不动文件清单 / 禁止事项之外的文件。怀疑根因在范围外时，停下来报告，不擅自扩散修改。
- 修不对就回滚。一处修改重跑仍失败，先回滚这次改动再换假设，不要在错误改动上叠加。
- 不 commit / push / merge。
- 超过 3 轮"假设→修复→重跑"仍未绿 → 停止，升级给强模型或回报人工，不无限烧 token。
工作流
1. 固定失败信号（不复现不动手）
- 把失败的原文贴出：报错堆栈 / 失败断言 / 命令非零退出码及输出。
- 确认能稳定复现：记下复现命令（取自
prd.md 自检命令或测试命令）。
- 复现不了就先解决"不稳定复现"，不要对着偶发现象瞎修。
- 把复现命令、失败原文和是否稳定复现写入
<task-dir>/debug-report.md。
2. 定位（只用三招，缩小到具体行）
按代价从低到高，命中即停：
- 读栈：报错堆栈/断言指向的文件与行，直接看那一处。
- 二分注释：对可疑代码段二分注释/短路，看失败是否消失，缩小范围。
- 加一行日志：在缩小后的范围打印关键变量的实际值，对比期望值。
输出：把范围缩小到"具体文件 + 具体行/变量"，不再泛泛说"哪里有问题"。
3. 单一假设（先验证真假，再谈修）
- 写一句话假设：
我认为根因是 X（具体到变量/分支/契约）。
- 先用最小手段验证假设真假（看变量实际值、查契约、跑一个更小的探针），确认了再修。
- 假设被证伪 → 回到步骤 2 换一处，不要带着错假设去改。
4. 最小修复 + 回归
- 只针对已验证的根因改一处。
- 重跑原失败命令 → 绿则继续；仍红则回滚本次改动，回步骤 3 换假设。
- 绿之后跑
prd.md 自检命令全集，确认没引入新的红（无回归）。
- 防御性收尾：回答一句"这个 bug 还能从别的入口再发生吗？"
- 能 → 在
check.jsonl 记一条回归点（{"file":"<回归测试或风险点>","reason":"<它保护的行为>"}），并考虑补一个回归测试。
- 不能 → 在调试记录里写明"已局部封闭"。
5. 退出
- 绿了：回到
trellis-implement-tdd-zh 失败的那一步继续。
- 已回滚且换不出有效假设：记录已排除的假设，升级。
- 超 3 轮仍红：停止，升级给强模型 / 人工，附上失败信号、已试假设、已排除项。
小模型适配要点
- 调试是小模型最容易失控的环节——本技能用编号步骤 + 一次一处 + 改完必重跑把它变成机械流程。
- "禁止猜、先验证假设"避免小模型把"看起来相关"的代码乱改一通。
- 明确的退出与升级条件，避免小模型陷在调试里反复烧 token。
- 角色分层：调试默认小模型执行；超 3 轮升级强模型。
参考文件
references/debug-protocol.md —— 4 步脚本的判据细节、三招定位法与反模式，开始调试前读取。references/debug-report-template.md —— <task-dir>/debug-report.md 的只读模板；调试过程中全程更新任务目录下的固定文件。
