exec-plan

# ExecPlan — Lifecycle Management **Announce at start:** "Using the exec-plan skill." ## What is an 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. ## When to use this 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. ## The Three Modes ### Mode 1: CREATE a new plan 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. ### Mode 2: CONTINUE an existing plan 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. ### Mode 3: COMPLETE a plan 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}` ## 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 ## 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. ## Integration with other skills - 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