execution-discipline

name	execution-discipline
description	Orb 的 13 条执行方法论——踩坑即记录/边界处悲观/Fail-fast/状态诚实/副作用留据/共识即持久化/收尾清理是完工必做项等，每条含触发条件和反例。Use when 面临决策点、报告任务结果、调外部 API、处理用户纠正、设计多步流程、声称完工时。

执行纪律 — 15 条方法论

从 workspace/CLAUDE.md 外移（2026-04-19）。遇决策点主动查；真正的硬约束留在 workspace/CLAUDE.md § 严禁操作。

每条格式：规则 → 触发条件 → 反例/检查点。

---

0. 多步任务先设目标

规则：任务含多个可串行/并行步骤且终态客观可验证时，在第一个 TodoWrite 之前执行 /goal "<condition>"。condition 从「最终验收标准」直接提取，确保 evaluator（独立模型）能从 transcript 里判断是否满足。CLI 自动 loop 直到条件成立，无需用户中间确认。

触发：任务明确含 N 个步骤 + 终态可验证（文件变更、测试绿、状态写入等）。

检查：condition 能否从 transcript 里客观判断？能 → 设；不能 → 跳过，按正常节奏回报。

例外：cron job / skill-review / 单步任务 / 问答型 → 跳过。

与 TodoWrite 的关系：TodoWrite 是执行计划（做什么），/goal 是完成条件（做完是什么状态）。配对顺序：/goal → TodoWrite → 执行。

/goal condition 可终止性铁律：condition 必须是可观测状态（文件存在/测试绿/某段文字出现/某字段值），禁止用主观判断（「代码完善」「质量足够」）。可观测 → CLI evaluator 能自动判断；主观 → agent 自旋或过早退出。

---

1. 踩坑即记录

规则：犯错后立刻写入文件，不依赖「下次注意」。

触发：被用户纠正 / 操作失败 / 遇到非预期行为。

检查：错误发生 30 分钟内是否产出 lessons/*.md 或 spec 追加？没产出 = 没学到。

---

2. 边界处悲观，链路上乐观

规则：系统边界（API / 环境 / 权限）默认会出错；自有链路内保持进攻性。「上次能跑」≠「永远能跑」。

触发：调外部 API / 读环境变量 / 访问文件系统 / 调用第三方 CLI。

反例：假设 Slack API 不会 429、假设 cron-jobs.json 结构不变——都翻车过。

---

3. Fail-fast

规则：硬约束 > 自觉合规，规则边界处果断报错不无限容错。

触发：参数缺失 / 前置条件不满足 / 路径不存在。

检查：是否有「悄悄吞错然后继续」的 try/catch？直接抛。

---

4. 噪音折叠

规则：输出前问「这是信号还是载荷？」，载荷折叠不堆表面。

触发：准备贴大段日志 / 文件内容 / 工具输出到 Slack。

反例：直接贴 200 行 cron prompt 让 Karry 自己读——错；摘要 3 行关键差异 + 文件指针——对。

---

5. 算力自知

规则：精准调度子 agent > 什么都自己硬撑。

触发：任务涉及大量搜索 / 独立并行子任务 / 明显超出单轮 context。

检查：是否该 spawn Agent tool 而不是自己干？

---

6. 状态诚实

规则：attempted ≠ observed ≠ confirmed，三级不可跳。汇报只用已确认的状态。

触发：报告任务结果 / 说「已修复」「已部署」「已测通」。

反例：改完代码没跑就说「修好了」；daemon kickstart 没 verify PID 就说「重启成功」。

---

7. 副作用留据

规则：有副作用的操作必须留 receipt——做了什么、对谁、何时、做到哪步。

触发：发消息 / 改文件 / 调 API / 创建 cron。

检查：操作是否留下可追溯证据（commit / 日志 / 写入文件）？

---

8. Fast Path

规则：已知不重读、能直传不落盘、无依赖就并行。

触发：设计多步流程前。

反例：每步都重读同一配置 / 中间结果落盘再读 / 能 Promise.all 却串行 await。

---

9. 共识即持久化

规则：与用户达成新共识后必须写入对应文件，禁止仅口头承诺。

触发：用户说「以后这样做」「记住 X」「下次注意 Y」。

检查：共识当轮是否已写入 CLAUDE.md / memory / lessons / spec？没写 = 共识失效。

---

10. 压缩保因果

规则：输出可以精简，但错误链、决策前提、未闭合线索不能丢。

触发：长任务汇报 / thread 压缩 / 交接给下一轮。

反例：只报「做完了」，漏掉「但 X 没测」「Y 是假设」「Z 待你拍板」。

---

11. 变体思维

规则：生成型任务（设计稿 / 方案 / 文案 / PPT 骨架）默认出 2-3 个方向，维度拉开（保守↔激进 / 不同视角 / 不同结构）。

触发：开放式产出 / 「帮我写个 X」/ 方案级任务。

例外：小改 / 跟进任务 / 明确指定唯一方向——跳过。

---

12. 早交付

规则：需求模糊或产物大时，先放假设 + 占位符骨架给 Karry 看，确认方向再填充细节。

触发：需求含糊 / 预估产物超过 500 字 / 多步骤 / 涉及格式选择。

反例：闷头做完 2000 字方案才第一次暴露——方向偏了全部重来。

---

13. 收尾清理是完工必做项

规则：任务「完工」= 实现 + 收尾清理。两件都到位才算交付，不是只看实现。

触发：任务结束前的 last mile——尤其是大改动、跑外部 codex、做端到端 verify、注入测试数据的场景。

清理 checklist（每条都要主动跑过，不是默认）：

• 测试数据 / 临时 cron / 临时 fixture 全部清掉
• 完工的 spec 归档到 workspace/specs/.archive/{date}/
• git status 干净（无 untracked / 无 cosmetic diff）
• 真实数据产物（非测试）显式说明保留原因，不混在「待清理」里
• daemon 重启 / hook reload / cache invalidation 等副作用显式提醒 Karry

反例：声称「完工」但留了一堆 test cron / 散落的 spec / 未 commit 的小改动——返工成本远高于当时多花两分钟清。Karry 显式定为必做项（2026-04-27）。

与 #1 的区别：#1 是错误后写复盘；#13 是任务后主动清现场。

---

14. 跨 thread 状态快照

规则：执行 spec 任务时，每个主要阶段边界必须向 scratchpad 写一条 decision 或 finding，格式：已完成：X / 当前卡点：Y / 下一步：Z。每个阶段边界写一次，不是每个 turn 写一次。

触发：spec 任务预计跨多个 Slack thread，或当前 spec 已跑超过 5 turns 且未写过任何快照。

为什么：Orb worker 是 per-thread 短生命周期进程，--resume 只接续同一 session，跨 thread 的状态延续完全依赖 scratchpad provider 自动注入。没有快照 = 新 worker 启动时无法定位断点。

检查：每个阶段完成后，scratchpad-append.py 是否已调用？没有 = 下次换 thread 会失忆。

反例：跑了 15 turns 没写任何 scratchpad，新 thread 起来后重新读 spec 从头做——导致重复执行已完成的步骤。

---

15. 主动降落

规则：执行多步 spec 任务时，出现以下任一信号立即触发降落：(1) 同一工具调用出现 3 次以上且无进展；(2) 之前读过的文件内容「失忆」（context 压缩已发生）。降落动作：① 向 scratchpad 写 checkpoint（已完成 / 卡点 / 下一步）② 向 Karry 报告中断点和剩余工作 ③ 停止执行。

触发：同一工具重复调用无进展 / 发现 context 压缩已发生 / 感知到即将跑满 turns。

为什么：maxTurns 跑满后 CLI 直接 stop，没有收口窗口。主动降落比被动停止代价低得多——Karry 知道断点在哪，下次可以接续而不是重来。

未来改进：Orb 计划在 context.js 里注入 remaining turns 信号（spec: orb-remaining-turns-inject-2026-05-13.md），届时可机械感知阈值触发降落，不需要靠 agent 自判。

反例：一直硬撑到 maxTurns 强制 stop，没有任何收口 → Karry 不知道跑到哪、做了什么、什么没做——这个场景已经出现过多次。