exec-plan

ExecPlan — 生命周期管理

开始时声明：“正在使用 exec-plan 技能。”

什么是 ExecPlan

一份独立、持续更新的文档，新会话中的 Agent 可以按照它交付可观察、可用的功能。存放在 docs/exec-plans/ 中。其格式遵循 docs/PLANS.md 中的规范。

ExecPlan 不是待办事项列表。它以叙述的方式讲述变更：为何重要、代码库当前的状态、变更完成后的状态，以及如何证明变更有效。

何时使用此技能

• 对于多步骤或涉及多个文件的工作、新功能、重构，或预计耗时超过约 1 小时的任务，必须使用。
• 对于简单修复，可以选择使用；但如果重大任务跳过此步骤，请说明原因。
• 从之前的会话恢复工作时，始终使用。

三种模式

模式 1：创建新计划

开始新的多步骤工作时：

1. 阅读 docs/PLANS.md 中的模板和要求。
2. 在 docs/exec-plans/active/{descriptive-kebab-name}.md 创建计划。
3. 填写模板中的所有部分。以下部分不可缺少：
   • Purpose / Big Picture — 变更完成后，用户可以看到或执行什么
   • Progress — 为每个里程碑列出未勾选的复选框
   • Surprises & Discoveries — 以 (none yet) 开头
   • Decision Log — 以 (none yet) 开头
   • Outcomes & Retrospective — 以 (fill when complete) 开头
   • Context and Orientation — 完整文件路径、术语定义、当前状态
   • Plan of Work — 按里程碑叙述目标 → 工作 → 结果 → 验证
   • Concrete Steps — 确切命令及预期输出
   • Validation and Acceptance — 可观察的成功证明
   • Idempotence and Recovery — 如何重试或回滚
4. 每个文件路径都必须从代码仓库根目录开始写出绝对路径。
5. 必须在文中定义每个术语——假设读者对相关内容一无所知。
6. 在开始实现前提交计划。

模式 2：继续现有计划

恢复工作或执行下一个里程碑时：

1. 阅读 docs/exec-plans/active/ 中的计划文件。
2. 找到 Progress 中第一个未勾选的项目。
3. 开始工作前，检查之前会话中的 Surprises 是否会影响此任务。
4. 按照 Plan of Work 执行里程碑。
5. 每完成一个里程碑后，立即更新计划：
   • 为 Progress 项目打勾并添加时间戳：- [x] (YYYY-MM-DD HH:MMZ) Description
   • 添加遇到的 Surprises & Discoveries
   • 添加所做选择对应的 Decision Log 条目
6. 将计划更新与代码变更一并提交。
7. 运行 Validation 命令确认成功。

重要：除非更新了计划文件，否则绝不要声称里程碑已完成。计划是持久化机制。如果不更新它，下一个会话就会重复已完成的工作。

模式 3：完成计划

所有里程碑完成后：

1. 填写 Outcomes & Retrospective 部分：
   • 实际成果与计划目标的对比
   • 尚存的差距
   • 经验总结
   • 意外的收益或成本
2. 移动文件：git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md
3. 使用提交信息：docs: complete exec-plan {name}

质量检查

提交任何新计划或更新后的计划之前，请确认：

• Purpose 描述的是用户可见的行为，而不只是代码变更
• Progress 中已完成的项目包含时间戳
• Context 使用从代码仓库根目录开始的完整路径标明文件
• 所有术语都在文中定义（关键术语不得仅引用外部文档）
• Validation 包含确切命令和预期输出
• Recovery 部分说明每个高风险步骤的回滚方法
• Surprises 部分为最新状态，即使内容为空也一样
• Decision Log 记录实现过程中做出的选择

反模式

• 只有检查清单，没有叙述：- [ ] Edit file X 对下一个会话毫无帮助。为什么要编辑它？要做哪些更改？如何验证？
• 将关键上下文放在外部参考中：See ARCHITECTURE.md for details——计划必须自成一体。请将相关上下文复制进来。
• 忘记更新进度：这是最常见的问题。如果你完成了一个里程碑，却没有勾选对应事项并添加时间戳，下一个会话就会重新执行。
• 将已完成的计划留在 active/：所有里程碑完成后，将计划移至 completed/。active/ 中只应保留尚未完成的工作。
• 跳过验证：Tests pass 不能作为验收标准。isValid 计算属性已不再存在于文件中，且通过运行 grep -n isValid file.swift 未返回任何结果来验证，这才是验收标准。

与其他技能集成

• 实施涉及 TCA 代码的计划里程碑前：调用 /pfw-composable-architecture
• 实施涉及调试的计划里程碑前：调用 debug 技能
• 实施涉及重构的计划里程碑前：调用 refactor 技能
• 实施涉及 API 设计的计划里程碑前：调用 rest-api-design 技能
• 完成所有计划里程碑后：调用 refactor 技能进行最终清理