Back to Details

exec-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ExecPlan — Lifecycle Management

ExecPlan — 生命周期管理

Announce at start: "Using the exec-plan skill."
启动时需声明： "Using the exec-plan skill."

What is an ExecPlan

什么是ExecPlan

A self-contained, living document that a fresh agent session can follow to deliver observable, working behavior. Lives in 
docs/exec-plans/
. The format follows the specification in 
docs/PLANS.md
.
An ExecPlan is NOT a todo list. It is a narrative that tells the story of a change: why it matters, what the codebase looks like now, what it should look like after, and how to prove it worked.
一个独立的动态文档，新的Agent会话可以遵循该文档交付可观测的可用功能。存放在
docs/exec-plans/
目录下。格式遵循
docs/PLANS.md
中的规范。
ExecPlan不是待办清单。它是讲述变更来龙去脉的叙述性文档：为什么要做这次变更、代码库当前是什么状态、变更后的预期状态是什么、以及如何证明变更生效。

When to use this skill

何时使用该skill

  • Required for multi-step or multi-file work, new features, refactors, or tasks expected to take more than about an hour.
  • Optional for trivial fixes, but if you skip it for a substantial task, state the reason.
  • Always when resuming work from a previous session.
  • 必须使用：多步骤或多文件的工作、新功能开发、重构、或预计耗时超过1小时的任务。
  • 可选使用：琐碎的修复任务，但如果您跳过为重要任务创建ExecPlan，请说明原因。
  • 必须使用：从之前的会话恢复工作时。

The Three Modes

三种模式

Mode 1: CREATE a new plan

模式1：CREATE 新建计划

When starting new multi-step work:
  1. Read 
    docs/PLANS.md
    for the template and requirements.
  2. Create the plan at 
    docs/exec-plans/active/{descriptive-kebab-name}.md
    .
  3. Fill ALL sections from the template. Non-negotiable sections:
    • Purpose / Big Picture — what the user can see/do after the change
    • Progress — empty checkboxes for each milestone
    • Surprises & Discoveries — start with 
      (none yet)
    • Decision Log — start with 
      (none yet)
    • Outcomes & Retrospective — start with 
      (fill when complete)
    • Context and Orientation — full file paths, term definitions, current state
    • Plan of Work — narrative milestones with goal → work → result → proof
    • Concrete Steps — exact commands with expected outputs
    • Validation and Acceptance — observable proof of success
    • Idempotence and Recovery — how to retry or roll back
  4. Every file path must be absolute from repo root.
  5. Every term must be defined inline — assume the reader knows nothing.
  6. Commit the plan before starting implementation.
当启动新的多步骤工作时：
  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. 开始实现前先提交计划文件。

Mode 2: CONTINUE an existing plan

模式2：CONTINUE 执行现有计划

When resuming work or executing the next milestone:
  1. Read the plan file in 
    docs/exec-plans/active/
    .
  2. Find the first unchecked item in Progress.
  3. Before starting work, check: are there any Surprises from previous sessions that affect this task?
  4. Execute the milestone following the Plan of Work.
  5. After each completed milestone, IMMEDIATELY update the plan:
    • Check the Progress item with a timestamp: 
      - [x] (YYYY-MM-DD HH:MMZ) Description
    • Add any Surprises & Discoveries encountered
    • Add any Decision Log entries for choices made
  6. Commit the plan update alongside the code changes.
  7. Run the Validation commands to confirm success.
CRITICAL: Never claim a milestone is done without updating the plan file. The plan IS the persistence mechanism. If you don't update it, the next session will redo the work.
当恢复工作或执行下一个里程碑时：
  1. 阅读
    docs/exec-plans/active/
    目录下的计划文件。
  2. 找到Progress中第一个未勾选的条目。
  3. 开始工作前，请检查：之前会话中记录的意外情况是否会影响当前任务？
  4. 按照Plan of Work执行里程碑。
  5. 每个里程碑完成后，必须立即更新计划：
    • 勾选Progress条目并添加时间戳：
      - [x] (YYYY-MM-DD HH:MMZ) 描述内容
    • 添加所有遇到的意外情况和发现到Surprises & Discoveries
    • 将所有决策记录添加到Decision Log
  6. 将计划更新与代码变更一起提交。
  7. 运行验证命令确认执行成功。
重要提示：绝对不要在未更新计划文件的情况下声称里程碑已完成。 计划是持久化机制，如果不更新，下一个会话会重复执行这部分工作。

Mode 3: COMPLETE a plan

模式3：COMPLETE 完成计划

When all milestones are done:
  1. Fill the Outcomes & Retrospective section:
    • What was achieved vs what was planned
    • Any remaining gaps
    • Lessons learned
    • Unexpected benefits or costs
  2. Move the file: 
    git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md
  3. Commit with message: 
    docs: complete exec-plan {name}
当所有里程碑都完成时：
  1. 填充Outcomes & Retrospective章节：
    • 实际完成内容与计划内容的对比
    • 剩余未解决的问题
    • 经验教训
    • 意料之外的收益或成本
  2. 移动文件：
    git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md
  3. 提交信息为：
    docs: complete exec-plan {name}

Quality Checks

质量检查

Before committing any plan (new or updated), verify:
  • Purpose describes user-visible behavior, not just code changes
  • Progress has timestamps on completed items
  • Context names files by full path from repo root
  • All terms are defined inline (no "see external doc" for critical terms)
  • Validation has exact commands AND expected outputs
  • Recovery section explains rollback for each risky step
  • Surprises section is up to date (even if empty)
  • Decision Log captures any choices made during implementation
提交任何计划（新建或更新）前，请确认：
  • Purpose描述的是用户可见的行为，而不仅仅是代码变更
  • 已完成的Progress条目带有时间戳
  • Context中使用从仓库根目录开始的完整文件路径
  • 所有术语都在文档内定义（关键术语不得出现「参考外部文档」的说明）
  • Validation部分包含准确的命令和预期输出
  • Recovery章节说明了每个风险步骤的回滚方式
  • Surprises章节是最新的（即使是空的）
  • Decision Log记录了实现过程中做出的所有选择

Anti-patterns

反模式

  • Checklist without narrative: "- [ ] Edit file X" tells the next session nothing. WHY edit it? WHAT changes? HOW to verify?
  • External references for critical context: "See ARCHITECTURE.md for details" — the plan must be self-contained. Copy the relevant context in.
  • Forgetting to update Progress: The most common failure. If you finish a milestone and don't check the box with a timestamp, the next session will redo it.
  • Leaving completed plans in active/: After all milestones are done, MOVE to completed/. Active plans should only be unfinished work.
  • Skipping Validation: "Tests pass" is not acceptance. "The 
    isValid
    computed property no longer exists in the file, verified by 
    grep -n isValid file.swift
    returning no results" IS acceptance.
  • 没有叙述性内容的检查清单： "- [ ] 编辑文件X"这样的内容对后续会话毫无价值。为什么要编辑？要做什么修改？如何验证修改正确？
  • 关键上下文依赖外部引用： "See ARCHITECTURE.md for details"——计划必须是自包含的，请把相关上下文复制进来。
  • 忘记更新Progress： 最常见的错误。如果你完成了一个里程碑但没有勾选条目并添加时间戳，下一个会话会重复执行该部分工作。
  • 已完成的计划留在active/：所有里程碑完成后，请移动到completed/目录。active/目录下应该只存放未完成的工作。
  • 跳过验证： "测试通过"不代表验收通过。"The 
    isValid
    computed property no longer exists in the file, verified by 
    grep -n isValid file.swift
    returning no results"才是符合要求的验收证明。

Integration with other skills

与其他skill的集成

  • Before implementing plan milestones that involve TCA code: invoke 
    /pfw-composable-architecture
  • Before implementing plan milestones that involve debugging: invoke the 
    debug
    skill
  • Before implementing plan milestones that involve refactoring: invoke the 
    refactor
    skill
  • Before implementing plan milestones that involve API design: invoke the 
    rest-api-design
    skill
  • After completing all plan milestones: invoke 
    refactor
    skill for a final cleanup pass
  • 实现涉及TCA代码的计划里程碑前：调用
    /pfw-composable-architecture
  • 实现涉及调试的计划里程碑前：调用
    debug
    skill
  • 实现涉及重构的计划里程碑前：调用
    refactor
    skill
  • 实现涉及API设计的计划里程碑前：调用
    rest-api-design
    skill
  • 完成所有计划里程碑后：调用
    refactor
    skill做最终清理