Writing Plans

计划让实际接手者能够按原始愿景实施与验收。历史上既有把模板写得很细却偏离目标，也有遗漏状态边界、留给 reviewer 逐轮补课的问题；计划应消除这些歧义。

必须做到

• 回读已接受的原始需求、feature/spec 与相关决定，写清本计划的目标、覆盖范围、验收要求和来源。计划分步不等于缩减愿景或把未完成包装成已完成。
• 关键依赖、契约和改动位置足够明确，让接手者知道从哪里开始、哪些决定已定、什么仍需查证；无需重复抄写已有真相源全文。
• 每个工作单元有可观察的结果与适用验证。涉及行为/回归风险按 tdd；现有精准检查可以提供 RED，纯文档/机械改动走对应检查。
• 关键未决问题可见：技术问题由猫在职责内解决，真正的价值取舍附 Decision Packet；已接受范围内的可逆细节不重复询问 operator。
• 计划需要跨 session/跨猫消费时，保存在可追溯载体并持久化。通常使用 feature-specs/YYYY-MM-DD-<topic>.md；Git 载体按当前工作现场与仓库风险规则选择，不为写计划专门切回 main。

模板与例子是可选参考。可以照用、改造或换成更清楚的表达；不要求按固定分钟粒度拆动作，不要求预写完整实现，也不按模型资格决定谁可以不用模板。路径已经明确或已有详细计划时直接继续执行。

Stateful Object Gate：状态契约必须清楚

涉及有生命周期的对象时，识别本次新增或改变的状态及消费路径，包括复用现有 API 后新增的轮询、发送闸门或到达判定。必须讲清：

• 谁拥有生命周期，哪些事件改变状态，恢复/删除/list 等旁路如何与之保持一致；
• 哪些不变量必须成立，怎样观察或验证；
• 适用的 crash、并发、恢复和误用边界，以及对应预期。

已有契约直接引用，只补本次 delta。能由纯投影表达的状态不另存一份。转移表、编号不变量、图与测试矩阵都是可选表达，契约是否完整可验证才是判断依据。

来源：F229 PR #2202 多轮补状态边界，以及消费侧状态漏普查的教训。可参考 (internal reference removed)。

可选参考：从终态拆工作

1. 用一句话定义要达到的结果，核对验收要求和范围。
2. 找出真正影响实现的接口、状态和依赖；需要探索的问题用明确问题与可验证结论组织 Spike。
3. 按可实施、可验证的工作单元拆分。每步的产物要服务终态，避免把将来必重写的临时实现冒充交付。
4. 为接手者容易误解的边界给一个例子或局部代码；不为模板补全普通实现。

可选计划骨架

# <目标> 实施计划

来源：<原始需求 / feature / accepted decision>
目标与范围：<本计划兑现什么，哪些要求属于已接受的其他范围>
验收：<可验证要求，或准确引用已有 AC>
关键契约与依赖：<已定约束、相关状态/接口、先后关系>
未决问题：<技术 / 价值，以及解决路径>

## 工作单元：<可观察结果>
改动位置：<已核实的文件 / 模块>
行为与边界：<具体预期；需要时附图、表或局部代码>
验证：<当前仓真实命令 / 用户路径与预期结果>

F191/F303 的适用声明仍按 Design Gate 契约提供：Architecture cell / Map delta / Why，命中 consumer/authority 边界时补对应 evidence。普通增量写 Map delta: none，不因计划模板而重画架构图。

Formatting Command Contract

计划写到格式化步骤时，先从当前仓库的 package.json、CI 或现有脚本确认可执行命令及适用范围；不要凭跨仓库习惯猜 formatter。计划中必须写出已确认的完整命令和预期结果，禁止只写“run formatting”或“格式化”。

• 全仓自动修复：pnpm check:fix
• 仅格式化本次文件：pnpm biome format --write <files>
• 终态验证：pnpm check

若仓库真相源提供不同命令，以真相源为准，并在计划中标明来源。以上仅在计划确实需要该检查时选用，不构成每份计划的全仓检查要求。

常见误区

下一步

在已接受的愿景范围内继续实施；需要隔离时用 worktree，需要行为保护时用 tdd。尚缺价值决策则回对应讨论/Design Gate，计划本身不触发整条固定流程。