/plan-prompts

name: plan-prompts
description: 'Use when asked to "create a development plan", "generate execution prompts", "replan a milestone", "update DEVELOPMENT_PLAN.md", "start M5", or "adapt future milestones" after predecessor work changes the current repository design. Not for discovering an uncertain destination or unresolved decisions; use decision-map. Not for auditing an existing plan; use plan-review. Not for executing a stack; use stacked-prs.'
metadata:
  version: 3.1.0
  category: development
  tags: [planning, execution-prompts, milestones, adaptive-planning, stacked-prs, release-management, docs]
  difficulty: advanced
  phase: plan
  complements:
    - milestone-runner
    - stacked-prs
    - plan-review
    - task-decomposer
    - decision-map

Development Plan and Execution Prompts

Turn source documents and repository reality into the smallest plan that gets a user to a working result:

• `.docs/DEVELOPMENT_PLAN.md` — project destination, near-term commitments and a lightweight future roadmap.
• `.docs/EXECUTION_PROMPTS.md` — short `/goal` blocks for actionable milestones only.

This skill plans only. Do not implement code, create issues or branches, open PRs, or run the prompts.

Scope Boundary

| Situation | Package | |---|---| | Destination or the decisions needed to define it remain uncertain | `decision-map` | | Existing plan needs a challenge before implementation | `plan-review` | | Approved plan needs execution | `milestone-runner` |

Be judicious

A plan is a cost the executor pays on every milestone. Every sentence you write becomes work, a check or a stop condition for a later session. Write only what changes what the executor does.

1. **Size the plan to the work first.** Report the size class and its reason before writing anything.

| Size | Signal | Output | | --- | --- | --- | | Small | Fits in one PR | No plan files. Return one `/goal` prompt of ≤200 words in chat. | | Medium | A few PRs, one milestone or two | Plan of ≤2 pages; ≤600 words per active prompt. | | Large | Several milestones with real dependencies | Rolling-wave plan; ≤600 words per active prompt. |

2. **Source-backed does not mean necessary now.** Include an enabler or architecture change only if a current acceptance criterion, safety/current correctness need, mandatory rule or irreversible constraint requires it now. Name the consumer or constraint, why a simpler solution fails and the cost of waiting. Otherwise defer it with a concrete revisit condition, even when it supports the long-term vision. Preserve affordable change with clear boundaries and ordinary maintainable code, not universal future abstractions. 3. **Acceptance is what the user can do.** Write each active milestone's acceptance as `Done when <user/operator> can <interaction> and sees <result>`, plus runnable checks. Required provider checks and repository mandates remain gates; unavailable optional evidence is a follow-up, not permanent `BLOCKED` or `pending qualification`. Do not add hardening, paid validation, extra reviews, benchmarks, telemetry or docs merely for confidence. 4. **Prefer fewer, usable milestones.** Each commitment delivers a working vertical slice. A prerequisite-only milestone needs a necessary-now reason and named consumer, and explains why they cannot be combined. Separate the destination from this commitment: distant roadmap items describe outcomes, dependencies and unresolved constraints, not speculative files, PRs or checks. 5. **Omit empty sections.** No requirement-ID catalogues, scenario suites, evidence tiers or traceability matrices unless the source uses them. One table beats three paragraphs. 6. **Before saving, cut.** For every sentence ask: would deleting it change what the executor does? If not, delete it.

Inputs

| Input | Meaning | Default | | --- | --- | --- | | Folder path, explicit file list or request | Source requirements; with a file list, the first file is primary. A small request needs no source file. | Required | | `REPO_CONTEXT` | Target repo; inspect tooling, CI, conventions, partial implementation and release practice. | Greenfield | | `GLOBAL_CONSTRAINTS` | Constraints absent from the sources. | None | | `STACK_DEPTH_HINT` | Upper bound when a stack is justified, not a target. | One cohesive PR; shallow stack only for a real review, integration or dependency benefit. |

For large source sets, read documents and the repository through read-only subagents that return cited findings, then confirm load-bearing citations yourself. Decomposition and writing stay in this session. Skip delegation when the input is small.

Workflow

Phase 0 — Ground

1. List the capabilities, interfaces, data and constraints the sources require, with source references. 2. Inspect the repository: package manager, test/lint/type/CI commands, conventions, what already works, known defects, version source and `CHANGELOG.md`. 3. Write the product contract in five lines: user and problem; north-star workflow (trigger → interactions → result); done-when demonstration; non-goals; working behavior and safety to preserve. Distinguish the project destination from the next usable contribution. 4. Record `> ASSUMPTION:` for defensible defaults and `> GAP:` for missing or contradictory requirements. A contradiction about architecture, data, security or acceptance blocks only the milestones it affects. 5. For a replan, read the existing plan and prompts first. Map every old milestone to keep, combine, defer or drop with a one-line reason. Keep unresolved historical failures visible. Drop optional work explicitly rather than carrying it forward.

Summarize Phase 0 in chat only.

Phase 1 — Write the plan (medium and large)

# Development Plan — <System>

## 1. Goal
<Five-line product contract and near-term commitment. For replans: completed evidence and the old-milestone mapping table.>

## 2. Assumptions & Gaps
<`> ASSUMPTION:` / `> GAP:` entries, or "None.">

##