Reference · Model-invoked · On-ramp / standalone · 六相位诊断循环

diagnosing-bugs 速查

六相位诊断纪律的口袋版。完整教学见 Lesson 0015；原文见 SKILL.md（134 行）、 hitl-loop.template.sh、 docs 页。

一句话

难 bug 与性能回归的诊断循环：先造一条对这个 bug 能变红的命令，再谈理论。 没有 red-capable 的反馈环，就没有 Phase 2——这是整个 skill 的牙齿。

何时伸手

你说「diagnose」/「debug this」，或报告什么东西坏了、抛错、失败、变慢（frontmatter 的触发词，model-invoked，agent 会自己加载）
难的那类：一眼看不穿的 bug、间歇 flake、两个已知良好状态之间溜进来的回归
不要去：设计问题 → prototype；merge 冲突进行中 → resolving-merge-conflicts（合完行为不对再回来）；别人的 bug 堆积未分拣 → triage；明显的小笔误 → 直接修

六相位与各相位的闸门

相位	做什么	闸门（不满足不许往下走）
1 造反馈环（本体）	造一条 pass/fail 命令并调紧：更快、信号更尖锐、更确定	能点名一条已跑过一次的命令：red-capable（断言用户报的症状）· deterministic · fast（秒级）· agent-runnable
2 复现+最小化	跑红，确认是用户报的那个失败；一次砍一个、每砍重跑，削到最小	复现的正是用户的病（wrong bug = wrong fix）；剩下的每个元素都承重
3 列假设	3–5 个排序的假设，先列完再验证	每个可证伪：「如果 X 是因，改 Y 会消失 / 改 Z 会加重」；说不出预测 = vibe，丢掉；清单先给用户看，AFK 不阻塞
4 插桩	探针对应 Phase 3 的预测；一次只改一个变量	调试器 > 定向日志；永不「到处打日志再 grep」；日志带 `[DEBUG-xxxx]` 前缀；性能分支：先基线测量再二分
5 修复+回归测试	测试写在修复之前——仅当存在正确接缝	正确接缝 = 能按调用现场的真实方式复现 bug 模式；太浅 = 假信心；没有正确接缝本身就是发现，记入 Phase 6
6 清理+复盘	宣布完成前的五条勾选 + 「什么能防止它」	原始场景复跑不红 · 回归测试绿 · `[DEBUG-]` 全删 · 临时物清走 · 病因写进 commit/PR；架构答案移交 improve-codebase-architecture（修完之后提）

Phase 1 · 造环十法（大致按此顺序）

失败测试——够得着 bug 的任意接缝（unit / integration / e2e），首选
curl / HTTP 脚本——对着跑起来的 dev server
CLI 调用——fixture 输入，stdout 对已知快照 diff
无头浏览器（Playwright / Puppeteer）——断言 DOM / 控制台 / 网络
重放抓取轨迹——真实请求 / payload / 事件日志存盘后隔离重放
一次性 harness——最小子集 + mock 依赖，一次调用走到 bug 路径
属性 / fuzz——1000 个随机输入找失败模式（「有时输出错」）
二分 harness——自动化「状态 X 启动、检查、重复」，交 git bisect run
差分循环——同一输入跑旧版 vs 新版（或两套配置），diff 输出
HITL bash 脚本（最后手段）——模板驱动真人，KEY=VALUE 回喂 agent

环造对了，bug 就修好了九成。调紧三问：更快？信号更尖锐？更确定？ 30 秒还抖动的环 ≈ 没有环；2 秒确定的环 = 调试超能力。 Flake 的目标是抬高复现率（循环 100×、并行、加压、注入 sleep）： 50% 可调试，1% 不行。 真造不出环：停下来明说 + 列已试方法 + 向用户要环境访问 / 抓取物证（HAR、日志转储、core dump、带时间戳录像）/ 生产临时插桩许可。禁止无环进入假设。

金句锚点

「This is the skill. Everything else is mechanical.」（Phase 1 是本体）
「Build the right feedback loop, and the bug is 90% fixed.」
「No red-capable command, no Phase 2.」
「One breakpoint beats ten logs.」
「Untagged logs survive; tagged logs die.」
「Measure first, fix second.」（性能分支）
「Wrong bug = wrong fix.」（Phase 2 先确认是用户的病）

会改什么 / 不碰什么

类别	内容
只读	`CONTEXT.md`（若存在）和相关区域的 ADR——开篇要求，先建心智模型
留在仓库	回归测试（Phase 2 最小复现改写在正确接缝上）· 修复代码 · commit/PR 里的病因结论
临时，必须清	`[DEBUG-…]` 日志（前缀 grep 删净）· 一次性 harness / 脚本（删除或挪到明确标注的调试位置）
不碰	Issue tracker（不读不写工单）· CONTEXT.md / ADR（复盘只「移交」，落盘是 architecture / domain-modeling 那条线的事）

下一步

常规：修复+回归测试落地、commit 写明病因 → 回到被打断的工作；bug 来自 issue 就按常规关掉它
复盘指向架构（没有好接缝 / 调用方纠缠 / 隐藏耦合）→ 带具体情况进 improve-codebase-architecture
想把「防住这类 bug」变成正式工作 → 当新想法走主流程（grill-with-docs → to-spec → …）

依赖 / 被依赖

依赖：CONTEXT.md + ADR（读）；codebase-design 的 seam 词汇（Phase 5 判据）；tdd 的红绿纪律（回归测试先红后绿）
被依赖：ask-matt 的「Something's broken」on-ramp；prototype 与 resolving-merge-conflicts 的 docs 页把越界故障推给它；它的复盘是 improve-codebase-architecture 的候选来源之一

微调入口

症状	改哪段
没造环就讲理论	SKILL.md Phase 1「Completion criterion」+「No red-capable command, no Phase 2」
环选得不对 / 顺序乱	Phase 1「Ways to construct one」十项清单及顺序
对 flake 轻易宣布无法复现	Phase 1「Non-deterministic bugs」（抬复现率，50% 可调 / 1% 不行）
跳过最小化	Phase 2「Minimise」（一次砍一个、承重判据）
单假设开测 / 假设没法验证	Phase 3（3–5 排序 + 可证伪格式 + 先给用户看）
无标记日志、收尾没删	Phase 4 打标规则 + Phase 6 清理勾选
性能问题靠日志猜	Phase 4「Perf branch」（先基线测量再二分）
回归测试写在太浅接缝	Phase 5「correct seam」定义与反例
commit 没写病因	Phase 6 勾选清单最后一项
触发太灵 / 太钝	frontmatter `description` 的「Use when…」
HITL 脚本交互	`scripts/hitl-loop.template.sh` 的 step / capture
Codex 显示名 / 简介	`agents/openai.yaml`