plan

name	plan
description	当用户要为多步骤开发任务写计划、制定实现计划、规划或拆解任务，要求先规划再动手，或询问 “怎么实现这个功能”“给我个方案”且任务不止一步时使用。
metadata	{"openclaw":{"emoji":"📋"}}

plan — 实现计划编写技能

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

为多步骤任务编写可执行、无占位符、可独立验证的实现计划。 假设执行者对代码库零上下文：计划中写清每个任务的文件、接口、代码与测试步骤。

核心原则

1. 先有规格，再写计划：从需求/规格/设计文档出发，规格缺席时先澄清需求 （参考 brainstorming/make Step 1），不凭空规划。
2. 假设执行者零上下文：计划自包含——文件路径、接口签名、代码示例、验证命令 全部给出；读者可能跳序阅读，任务间依赖通过"Consumes/Produces"显式声明。
3. 任务粒度 = 最小的独立测试单元：每个任务自带测试周期（写失败测试 → 运行确认失败 → 最小实现 → 运行确认通过 → 交付检查），一步一动作（2-5 分钟粒度）； 配置/脚手架/文档步骤并入其交付物所属任务，不单列空任务。
4. 无占位符：禁止 TBD/TODO/"实现细节后补"/"类似任务 N"/"写测试"（无测试代码）/ "添加适当错误处理"（无具体内容）；每步必须给出执行者实际需要的内容。
5. DRY / YAGNI / TDD：不重复造轮子、不做超前设计、测试先行。
6. 文件结构先于任务分解：先锁定文件清单与职责边界（每个文件一个清晰职责， 一起变化的放一起），再据此分解任务。
7. 自审：计划完成后对照规格做覆盖检查、占位符扫描、类型/命名一致性检查。
8. 诚实边界：计划与规格矛盾、或有需求无法落实时如实说明，不硬编。

触发时机

• 用户要求计划："写计划"、"制定计划"、"实现计划"、"规划"、"拆解任务"、"任务分解"
• 用户要求先规划："先规划再动手"、"怎么实现这个功能"、"给个方案"、"做个计划"
• 规格已存在：用户给出 spec/设计文档要求转化为实现计划
• 与其他技能配合：计划执行（按计划实现）用 make 技能；计划实现报错用 debug； 性能不足用 optim；计划涉及的需求澄清可用 make Step 1 方法论

工作流程

Step 1. 明确规格与范围

1. 确认规格来源：需求文档/设计文档/用户描述；无规格时先澄清 （做什么、不做什么、验收标准——所有问题一次性全部提出，用户一次回答），输出一句任务定义；
2. 范围检查：规格覆盖多个独立子系统时，建议按子系统拆分计划， 每个计划独立可交付、可测试；拆分方式与用户一次确认。

Step 2. 设计文件结构（分解决策锁定点）

1. 先确定将新建/修改哪些文件、各自职责（一个文件一个清晰职责； 一起变化的文件放一起；按职责而非技术层拆分）；
2. 既有代码库遵循既有模式；不擅自重构大文件，但计划中可合理包含拆分；
3. 文件结构在终端摘要中说明，它是任务分解的依据。

Step 3. 任务分解与编写

按依赖顺序分解任务，每个任务：

### Task N: <组件名>

**文件:**
- 新建: `exact/path/to/file.py`
- 修改: `exact/path/to/existing.py:123-145`
- 测试: `tests/exact/path/to/test.py`

**接口:**
- 消费: <来自前面任务的内容——确切签名>
- 产出: <后续任务依赖的内容——确切函数名、参数与返回类型>

- [ ] **Step 1: 写失败测试**
      <测试代码>
- [ ] **Step 2: 运行确认失败**
      运行: `pytest tests/path/test.py::test_name -v` 预期: FAIL
- [ ] **Step 3: 最小实现**
      <实现代码>
- [ ] **Step 4: 运行确认通过**
      运行: `pytest ...` 预期: PASS
- [ ] **Step 5: 交付检查**
`git diff --check`；有 Git 且有本次改动时不自动暂存、提交或推送；用户明确要求时按指定范围执行。

计划文档头部：

# <功能名> 实现计划

**目标:** <一句话描述构建什么>
**架构:** <2-3 句方案>
**技术栈:** <关键技术/库>
**规格:** <规格/设计文档路径>
**全局约束:** <版本下限、依赖限制、命名与平台要求——逐行精确复制自规格>

Step 4. 自审（覆盖/占位符/一致性）

写完计划后以全新视角对照规格检查：

1. 规格覆盖：逐条核对规格要求 → 每个都能指向一个任务；缺口补任务；
2. 占位符扫描：全文搜索 TBD/TODO/“实现细节后补”/"类似任务 N"/ "添加适当错误处理"等模式并补全；
3. 类型与命名一致性：后置任务中的函数名/签名/属性名与前置任务定义一致 （Task 3 用 clearLayers()、Task 7 用 clearFullLayers() 即计划 bug）；
4. 发现的问题就地修复，不另开评审。

Step 5. 保存与交接

1. 保存计划到 docs/plans/YYYY-MM-DD-<feature-name>.md，同时在终端摘要中说明；
2. 向用户提供执行方式选择：
   • 本会话内联执行：按计划逐步执行（建议转 make 技能编排）；
   • 子任务代理执行：每任务派发独立子代理执行+审查；
   • 用户手动执行：计划交付给用户自行实施。

Step 6. 总结（结构化输出）

✓ 计划完成
   对象:   <任务定义>
   任务:   <N 个任务，每个独立可验证>
   规格:   <规格来源路径>
   计划:   docs/plans/YYYY-MM-DD-<feature>.md
   自审:   <覆盖检查 N 条需求全覆盖; 占位符扫描 0; 一致性检查通过>

   遗留:   <未覆盖项/待用户确认项，无则省略>

错误处理

场景	处理
无规格/需求含糊	先澄清需求（做什么/验收标准），不凭空规划
规格覆盖多个子系统	建议拆分为多个独立计划，与用户确认
计划过长	拆 references/ 或按子系统拆分计划，保持可读
任务依赖不明	通过 Consumes/Produces 显式声明接口，缺则补写
发现占位符	补全具体内容（路径/签名/代码/验证命令）后重审
命名/签名不一致	修正为一致后重审
需求无法落实	如实说明并建议修改需求或方案，不硬编

注意事项

• 计划必须自包含、可执行：执行者不应需要猜测或跳转查证；
• 计划文档属于本次交付物；交付前执行 git diff --check，不自动暂存、提交或推送。