用途:面向任意技术问题的系统化根因调试方法,触发场景包括 debug、修复、报错、失败、行为异常或卡住时。开始前要求先阅读 principles/fix-root-causes,全程遵循追根因、不掩盖症状的原则。
主要流程:一、复现,拿到确切报错并运行失败命令、读完整输出,无法复现就无法验证修复。二、阅读报错,把错误信息、堆栈和行号当作数据,先读完再提假设。三、先怀疑状态再怀疑代码,尤其针对重启类缺陷或环境漂移,需检查 Noodle 状态(.noodle/orders.json 是否有陈旧项、.noodle/sessions/ 是否孤立、.noodle.toml 是否有效)、tmux 会话(tmux ls)、锁文件与缓存产物、配置校验与技能前置元数据解析错误、持久文件(brain/ 笔记、计划文件、待办)是否损坏或引用陈旧。四、隔离,用二分法缩小到文件、函数、行。五、找根因,对第一个想到的修复继续追问为什么,并举了测试失败、构建失败、运行时崩溃三类追因链。六、修复并验证,跑测试、跑构建、走功能路径,编译通过不算验证。七、检查同类模式,全局搜索相同写法并全部修复或从结构上杜绝。
Noodle 诊断对照:Cook 无法启动先查 tmux ls、.noodle/orders.json 有效性、技能解析路径;订单卡住查 .noodle/orders.json 陈旧项与 .noodle.toml 适配器配置;技能缺失查 .noodle.toml 的 [skills] 路径及 .agents/skills/<name>/SKILL.md 是否存在;mise 陈旧查 .noodle/mise.json 的 generated_at 时间戳与 backlog 同步脚本;会话孤立查 .noodle/sessions/<id>/meta.json 状态与 tmux 僵尸会话。
卡住时的做法:加日志实测而非猜测、用 git diff/log/bisect 比对变化、最小化复现、一次只改一处、校验自以为正确的假设。
反模式:--no-verify、--force、SKIP_CHECK=true 等绕过标志;重试循环;散弹式调试;不加追问就加 undefined 判断。修复后若能复发或影响理解,应写 brain 笔记、更新技能或加待办,让系统从每个缺陷中变聪明。