write-plan

编写计划

概述

制定一份完整、独立的实施计划，让 execute-plan 能够在几乎没有歧义的情况下执行，即使是在 /clear 之后或由其他 Agent 执行也是如此。

此技能仅用于规划：

• 不要实现代码
• 不要修改生产文件（计划产物除外）

工作流程

步骤 1：梳理上下文

仅加载与所请求的更改相关的项目上下文：

• 如果存在 docs/SUMMARY.md，先阅读。
• 仅加载与任务相关的详细文档。
• 优先遵循 Code Standard 文档中的实现约定。
• 如果文档与代码或用户意图冲突，在进行大范围更改前使用可用的输入/提问工具。

然后，仅检查与所请求更改相关的代码区域。

记录：

• 面向用户的用途和预期结果
• 应遵循的现有模式
• 约束和依赖项
• 可为执行者提供指引的文件、模块、命令和文档
• 风险、假设和未知事项

步骤 2：初始化计划产物

1. 创建：docs/.plans/YYMMDD-HHmm-<plan-slug>/
2. 创建：
   • SUMMARY.md
   • 每个实施阶段对应一个阶段文件，命名约定为 phase-XX-<name>.md
3. 仅在需要时添加 research/。

规则：

• 使用共享的 General Principles 中的时间戳命令，生成文件夹和文档的时间戳。

步骤 3：澄清需求

提出澄清问题，消除请求中的任何歧义。重点关注：

• 范围和边界
• 成功标准
• 约束和非目标
• 优先级和权衡

规则：

• 如果需求已经明确或来自头脑风暴上下文，则无需确认步骤。
• 使用输入/提问工具收集回答和上下文。
• 在 SUMMARY.md 中明确说明假设。如果对请求存在多种解释，列出这些解释并提问，不要默默自行选择。

步骤 4：制定策略和阶段

设计安全且可验证的分阶段策略。

每个阶段应包含：

• 明确的目标
• 与该阶段相符的复杂度和风险级别，取值为：S、M、L、XL
• 按顺序排列的任务
• 验证命令
• 可观察的验收标准和退出标准

粒度规则：

• 任务应具体且规模较小。
• 优先选择可安全恢复执行的阶段。对于高风险工作，记录幂等性、恢复说明或回滚限制。

步骤 5：调研（仅在需要时）

调研为可选项，应与不确定性相称。

优先顺序：

1. 现有项目文档和代码
2. 现有技能和本地参考资料
3. 外部参考资料（仅限当前环境可访问的内容）

如果无法进行外部调研，请依据本地证据继续，并明确列出假设和未解决的问题。

将调研结果记录在：

• docs/.plans/YYMMDD-HHmm-<plan-slug>/research/<topic>.md

步骤 6：编写计划产物

• SUMMARY.md 格式
  遵循 references/summary-template.md 中的模板

• phase-XX-<name>.md 格式
  遵循 references/phase-template.md 中的模板

• 使用 visualize 技能将计划可视化；如果存在 --non-visualize，则跳过可视化。

步骤 7：审查和完善

提交计划前，确认：

• 路径准确且一致
• 阶段顺序合理
• 任务可执行（没有含糊的步骤）
• 每个阶段都定义了验证方式
• 验收标准可观察
• 风险和假设均已明确
• 无需当前聊天中的隐藏上下文即可执行计划

然后提交计划供用户审阅。

如果存在多种可行方案，提供选项，并请用户从以下选项中选择一项：（使用输入/提问工具进行选择）

• 确认：批准当前计划以供执行
• 验证：通过补充澄清问题进一步完善计划

步骤 8：交接

以以下内容结尾：

Plan `<relative_path_to_plan>/SUMMARY.md` is ready.

如果已创建可视化内容，还需包含：

Visualization `<relative_path_to_plan>/visualize.html` is ready.

规则

• 切勿在同一会话中自动实现或执行代码更改。只有在用户选择后，才允许可视化计划，且仅限计划相关产物。
• 优先使用明确的文件路径和具体命令
• 遵循项目规范和现有架构
• 保持计划自包含、确定且可恢复。新的 Agent 应仅凭计划文件夹即可继续执行。
• 规划最小可行更改： 不要规划推测性的阶段，不要添加“以防万一”的抽象，也不要加入未被要求的灵活性。如果计划可以分为 3 个阶段而不是 6 个，就分为 3 个。每项任务都必须直接对应一项明确提出的要求。
• 使用与当前会话相同的语言编写产物