milestone-planning

里程碑规划

目的

将清晰的方向转化为路线图结构。本技能负责文档治理，不负责任务级设计。

适用场景

• 规划方向已足够明确，可以进行拆解
• 仍需确定里程碑边界、模块分组或任务拆分方式
• 用户需要先获得路线图级任务，才能开始任务级 spec.md 工作

不适用场景

• 目标、约束或当前与后续阶段的边界仍确实不清楚
• 当前任务已从已确认的路线图状态中选出
• 当前工作是任务级规格说明、计划、实现或分支收尾

首先阅读

• docs/tasks/index.md
• docs/tasks/planning-inbox.md
• docs/tasks/backlog.md
• docs/tasks/ 下相关的里程碑、模块和任务文档
• 当前用户提示

负责

• 里程碑边界
• 可选的模块边界
• 路线图级任务拆解
• Roadmap confirmed 状态及其影响
• planning-inbox、backlog 和 Handoff Notes 治理
• 规划评审暂停点和规划交接上下文

不负责

• 任务级 spec.md
• 任务级 plan.md
• 执行隔离或实现
• 就绪检查、验证流程或分支收尾
• 伪装成路线图结构的实现级排序

入口检查

• 如果规划方向仍未明确，则返回 planning-clarification。
• 如果 Open Milestones 为空，则在拆解前检查 planning-inbox.md、backlog.md 和提示中的证据。
• 如果没有证据表明存在具体的短期目标或路线图偏差，则询问用户采用哪种规划模式。
• 如果用户要求在 Roadmap confirmed: no 的状态下开始工作，则在明确确认里程碑结构之前，保持拆解为暂定状态。
• 如果用户要进入后续里程碑，则先解决此前里程碑的收尾问题。
• 确认里程碑，或将 Roadmap confirmed: no 改为 yes 时，检查 backlog.md，查看是否有符合里程碑目标的延期任务。

默认流程

1. 确认当前问题涉及的是路线图结构，而非规划歧义。
2. 根据交付目标、阶段边界或退出标准确定里程碑边界，而非依据功能数量。
3. 仅当存在多个持久的能力领域，且它们在归属、风险、依赖关系、发布或验收边界方面各不相同时，才添加模块。
4. 按连贯的能力成果拆分路线图任务。每项任务都应可独立评审、独立交接并独立完成。
5. 确认里程碑后，将 backlog.md 中匹配的任务移入该里程碑，或明确将其保留为延期任务。
6. 在路线图文档中记录里程碑、模块和任务边界的理由。
7. 创建或调整路线图文档后，在规划评审暂停点停止。

边界规则

• 里程碑边界应体现发布或阶段意义，而不是为了让里程碑在视觉上大小均衡。
• 不要只因为原始请求范围广，就让一个庞大的里程碑一直保持开放状态。存在真实的阶段、退出或发布边界时，就应拆分。
• 模块是可选的。不要为一个能力领域创建一个包罗万象的模块。
• 不要把零散任务塞进很小的一次性模块中。
• 任务边界必须高于实现设计。路线图任务应说明要交付什么能力，而不是如何安排代码变更的先后顺序。
• 不要用 core、foundation、mvp 或 polish 等含糊的任务名称来隐藏多个可单独选择的能力。
• 不要以文件、端点、测试、迁移或重构切片为路线图任务命名。
• 除非治理工作本身就是面向用户的交付成果，否则不要将实现、测试、文档、验证或评审后续工作拆分成单独的路线图任务。
• 任务顺序应放在相关的有序列表中，而不是数字目录前缀中。
• 活跃里程碑期间新发现的未来工作，默认应首先记录在该里程碑的 Handoff Notes 中，而不是放进任务级的 plan.md。
• planning-inbox.md 用于存放目标和候选里程碑方向，而不是具体任务。
• backlog.md 用于存放具体的延期任务，而不是宽泛目标。

目标定义

• 目标是期望的未来状态、产品成果、机会或阶段方向。它说明应该实现什么以及其重要性，然后再决定路线图的形态。
• 目标通常应比一个实现任务范围更广，但不必非常庞大。它之后可能发展为一个里程碑、多个里程碑，也可能在澄清后被舍弃。
• 目标不是代码变更、端点、迁移、测试套件、重构切片或已经可以单独选择的实现成果。
• 如果某项内容无需先确定阶段方向，就能直接写成一份包含成果、大致范围、验收清单和成功信号的具体 task.md，则应将其视为任务，而非目标。
• 如果将规划收件箱中的某项提升为里程碑后，自然会生成一个名称相同的单一任务，且无需再作出其他边界决策，那么应将其重新归类为待办任务或当前里程碑任务，除非它本身确实构成发布、迁移或阶段边界。
• 目标应按成果或阶段命名，而非按可能采用的实现机制命名。

示例：

• 合适的规划收件箱目标：API contract stability，目标描述可以是“让后端响应足够可预测，使前端和外部客户端能够一致地处理成功、验证失败和业务失败。”
• 属于任务而非目标：Unify API business error model and response envelope。它已经说明了具体的实现成果，很可能可以直接成为一份 task.md。
• 对这类任务更合适的分类：将 Unify API business error model and response envelope 放入 backlog.md 或当前里程碑，并可选择将其归入 API contract stability 这样的目标。
• 从该目标衍生的合适里程碑：API Contract Stabilization，其退出标准应包括已记录的响应语义、对客户端安全的兼容性以及契约测试。
• 该里程碑下的合适任务：Define response envelope and business error semantics、Adapt callers to the unified response contract 和 Add API contract coverage and migration notes。
• 不合适的提升方式：规划收件箱目标 Unify API business error model and response envelope -> 里程碑 Unify API business error model and response envelope -> 单一任务 Unify API business error model and response envelope。这会让不同层级重复使用相同标签，而不是作出路线图决策。

Handoff Notes 路由

• 将 Handoff Notes 记录在当前里程碑的 index.md 中，而不是任务本地的 plan.md 中。
• 只有必须完成才能满足当前里程碑退出标准的事项，才留在当前里程碑中。
• 如果某事项明显属于未来的里程碑级工作，但并非结束当前里程碑所必需，则将其移至后续里程碑。
• 如果某事项是具体的任务级后续工作，且未分配给任何里程碑，则将其移至 docs/tasks/backlog.md。
• 如果某事项是尚未准备好成为里程碑的目标、阶段、机会或方向，则将其移至 docs/tasks/planning-inbox.md。
• 只有在某事项被明确放弃或不再值得跟踪时，才将其移除。
• 如果用户明确决定某事项优先级足够高，应中断当前进程，则重新规划该事项，而不是仅将其作为交接后续事项保留。

任务状态生命周期

• 新路线图任务的初始状态为 planned。
• 任务仅经过拆分、排序或选为未来候选项时，保持 planned 状态。
• 只有在实际开始任务本地的准备工作或实施工作时，才将任务改为 in_progress。
• 仅当所选任务因外部依赖、未解决的决策、未通过的前置条件或明确的停止条件而暂时无法推进时，才使用 blocked。
• 不要仅根据路线图规划将任务标记为 completed；任务应在实施、验证、必要的文档／状态更新以及收尾结果均已解决后，于执行阶段完成。
• 始终将任务的 Status 保持为单选状态。

规划收件箱

• planning-inbox.md 属于目标层，用于存放未来的产品目标、机会、候选阶段和长期路线图方向。
• 规划收件箱中的目标应描述需要规划的未来状态或阶段，而不是将要实施该目标的确切任务。
• 不要在 planning-inbox.md 中存放具体的任务级工作；除非该工作属于开放的里程碑，否则应将其移至 backlog.md。
• 当某个目标准备好成为开放的里程碑，或需要澄清规划时，将其从 planning-inbox.md 中移出。
• 将规划收件箱中的目标设为里程碑时，检查 backlog.md 中是否有与该目标匹配的延期任务。

待办事项

• backlog.md 属于任务层，用于存放值得保留但未分配给开放里程碑的具体延期任务。
• 待办事项应具有任务形态：包含结果、大致范围、来源，以及合理的目标或里程碑归属。
• 在里程碑规划、里程碑确认，或将 Roadmap confirmed: no 改为 yes 并因此纳入当前里程碑考量时，将相应事项从 backlog.md 中移出。
• 待办事项晋升为里程碑任务、被明确放弃或被其他任务取代后，将其从待办中移除。

遇到阻塞时

• 当没有证据能确定具体的短期目标或存在目标偏差时，询问规划模式问题：
  • 本次迭代已经有明确的短期目标，还是需要先重新调整路线图下一阶段的方向？
• 如果路线图结构仍取决于未解决的目标或边界歧义，则返回 planning-clarification。
• 如果未解决事项阻碍了里程碑确认、里程碑收尾或跨里程碑调整，则停止并直接询问。

评审与后续跟进

• 路线图文档变更后，在规划评审暂停点停止。
• 将该评审暂停点之后明确表示要继续推进的表述视为允许进行常规后续跟进。
• 评审后的默认常规跟进为：
  • 提交已评审的规划文档
  • 除非用户明确要求暂不提交
  • 然后报告交接背景，并推进至下一适用阶段
• 不要将规划评审通过视为可以跳过尚未解决的硬性关卡。

硬性门槛

• 如果较早的里程碑仍处于开放且未解决状态，不要进入后续里程碑。
• 如果路线图结构仍明确处于未确认状态，不要将 continue 视为里程碑确认。
• 只要 Handoff Notes 中还有未解决的事项，就不要结束里程碑。
• 不要向已完成的里程碑添加后续工作。请改为创建新的开放里程碑、待办任务或规划收件箱目标。

输出

• 建议的里程碑结构
• 说明是一个还是多个里程碑，以及原因
• 是否需要模块
• 每个里程碑或模块的任务列表
• 交付顺序（若不明显）
• 假设或未解决的问题

停止点

• 暂停规划审查
• 或直接提出有关路线图歧义、确认或结束的问题

交接

• Decided
• Undecided
• Next skill
• Stop point

参考资料

• 使用 references/roadmap-template.md 了解路线图文档的格式。