create-plan

What this skill does

# Create Plan

Transform a Product Requirements Document (PRD) into one or more self-contained Execution Plans (ExecPlans) that a coding agent or human novice can follow end-to-end without any prior context.

## Why ExecPlans matter

A PRD defines *what* to build and *why*. An ExecPlan defines *how* — the exact sequence of file edits, commands to run, and outputs to observe. The gap between a PRD and working code is where agents drift, retry, and produce noisy pull requests. An ExecPlan closes that gap by making every step explicit, every term defined, and every outcome verifiable.

The bar is high: a stateless agent reading only the ExecPlan file (with no memory of prior conversations, no access to the PRD, no external docs) should be able to produce working, observable results. If the plan requires knowledge that isn't in the plan itself, it fails this bar.

## How to run this skill

### Step 1: Locate and read the PRD

Ask the user for the PRD file path if not provided. Read it thoroughly — every section matters. Pay special attention to:

- **Epics and phase plan** — these become your milestones
- **Acceptance criteria** — these become your validation steps
- **Tech stack decisions** — these constrain your concrete steps
- **Build/run/validate commands** — these go directly into your ExecPlan
- **Architecture and repo boundaries** — these orient the reader
- **Non-goals and forbidden approaches** — these prevent scope creep

If the PRD has an ambiguity log with unresolved items, flag them to the user before proceeding. Unresolved ambiguity in the PRD becomes dangerous guesswork in the ExecPlan.

### Step 2: Decide the plan structure

A single PRD may produce one ExecPlan or several, depending on scope.

**One ExecPlan per epic** is the default when:
- The PRD has multiple epics that are independently deliverable
- Each epic takes more than a few file changes to implement
- Different epics touch different parts of the codebase

**One ExecPlan for the whole PRD** works when:
- The PRD describes a single cohesive feature
- The epics are tightly coupled and can't be implemented independently
- The total scope is small enough to fit in one plan without losing clarity

Ask the user which approach they prefer if it isn't obvious. When producing multiple ExecPlans, each must be fully self-contained — don't say "as described in ExecPlan 1"; repeat the context.

### Step 3: Research the codebase

Before writing anything, understand the current state of the repository. For each area the plan will touch:

1. Read the relevant source files to understand existing code structure
2. Identify the exact file paths, function names, module boundaries
3. Note any patterns the codebase follows (naming conventions, test organization, error handling)
4. Check for existing tests that cover the area you'll modify

This research is what makes the ExecPlan concrete rather than hand-wavy. You can't write "edit the handler function" — you need to write "in `src/api/handlers/user.ts`, modify the `createUser` function (line ~45) to add validation".

### Step 4: Write the ExecPlan

Use the skeleton from `references/exec-plan-guidelines.md` as your structural backbone. Every mandatory section must appear. Here is how to fill each one:

#### Title
Short, action-oriented. "Add JWT authentication to the API" not "Authentication Feature Implementation Plan".

#### Living document notice
State that this ExecPlan is a living document and that the Progress, Surprises & Discoveries, Decision Log, and Outcomes & Retrospective sections must be kept up to date as work proceeds.

#### Purpose / Big Picture
Two to four sentences explaining what someone gains after this change and how they can see it working. Write from the user's perspective: "After this change, you can..." followed by "To see it working, run X and observe Y." Pull this directly from the PRD's problem statement and acceptance criteria.

#### Progress
Start with all steps unchecked. Use checkboxes. Each step should be granular enough that checking it off is unambiguous. Group steps under milestone headings if there are multiple milestones.

#### Surprises & Discoveries
Start empty with a note: "No discoveries yet — this section will be populated during implementation."

#### Decision Log
Pre-populate with decisions already made in the PRD (tech stack choices, architectural decisions, rejected alternatives). Format each as: Decision, Rationale, Source (e.g., "PRD Section 8").

#### Outcomes & Retrospective
Start empty with a note: "To be completed at major milestones and at plan completion."

#### Context and Orientation
This is where self-containment lives or dies. Explain the current state of the repository as if the reader has never seen it. Name every file and module that matters, by full path. Define every non-obvious term. If the plan touches multiple areas, include an orientation paragraph explaining how those areas connect.

Do not say "see the architecture docs" or "as described in the PRD." Embed the knowledge here. If the PRD says the project uses Next.js with App Router, explain what that means for file organization in this specific project.

#### Plan of Work
Prose description of the sequence of edits and additions. For each change, name:
- The file (full repository-relative path)
- The location within the file (function, class, module)
- What to insert, modify, or remove
- Why this change is needed (connecting it back to the user-visible outcome)

Keep it concrete but don't paste entire code blocks here — that's what Concrete Steps is for. This section tells the story; Concrete Steps provides the recipe.

#### Concrete Steps
The exact commands to run and where to run them. Show working directory. When a command produces output, show a short expected transcript so the reader can compare. Use indented blocks for command output (not nested code fences).

Structure this as a numbered sequence. Each step should include:
1. What to do (plain language)
2. The exact command or edit
3. What you should see (expected output)
4. How to tell if it worked

#### Validation and Acceptance
Pull directly from the PRD's acceptance criteria, but translate them into concrete, runnable checks. "The API returns HTTP 200 with a valid JWT" becomes:

    curl -X POST http://localhost:3000/api/auth/login \
      -H "Content-Type: application/json" \
      -d '{"email": "[email protected]", "password": "test123"}'

    Expected: HTTP 200 with JSON body containing "token" field.

Include the project's test commands and expected pass counts. If the PRD specifies tests that should fail before and pass after, include both scenarios.

#### Idempotence and Recovery
Write steps so they can be run multiple times without damage. If a step creates a file, note that re-running will overwrite it. If a migration is destructive, spell out the rollback path. If a step can fail halfway, explain how to retry.

#### Artifacts and Notes
Include the most important terminal transcripts, short diffs, or log snippets as indented examples. Keep them focused on what proves success.

#### Interfaces and Dependencies
Name every library, module, and service the plan depends on, with versions where relevant. Specify the function signatures, types, and interfaces that must exist after implementation. Use stable, fully-qualified names.

### Step 5: Self-review the ExecPlan

Before presenting it to the user, verify against these criteria:

- **Self-contained**: Could someone with only this file and the repo produce working results? No references to "the PRD", "the architecture doc", or "as discussed earlier."
- **Novice-accessible**: Are all terms defined? Are file paths complete? Are commands copy-pasteable?
- **Outcome-focused**: Does every milestone end with something observable? Can the reader tell success from failure?
- **Idempotent**: Can steps be re-run safely?
- **Validated**: Are there concrete test commands with expected outputs?
- **Living-ready**: Are all fo