---
name: milestone-planning
description: Guide for planning development milestones grouped into phases and generating one phase file (phaseN-milestones.md) with the milestones and feature breakdown for each phase. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
allowed-tools: Read, Write, Edit
---

# Milestone Planning Skill

This skill explains how to break a product into ordered **phases** and **milestones**, and produce one phase file per phase under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation: every feature in every milestone is sized to be implemented with **one `/add-feature` run**, and every phase file is sized to be executed with **one `/execute-milestones` run**.

## Hierarchy

```
Roadmap (roadmap.md)
└── Phase (phase[N]-milestones.md — the /execute-milestones unit)
    └── Milestone (numbered globally: 01, 02, …)
        └── Feature (the /add-feature unit)
```

## Core Principles

1. **MVP first**: Phase 1 delivers the MVP; milestone 1 is its core — the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
2. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
3. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
4. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
5. **Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
6. **Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
7. **Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`.

## Inputs

Before planning, read:

- `docs/product-requirements.md` — user stories, priorities (P0/P1/P2), success metrics
- `docs/functional-design.md` — functional modules and data flows
- `docs/architecture.md` — technical constraints and dependencies
- `docs/design/ui-blueprint.json` (if present) — screens and user actions
- `docs/ideas/*` (if present)

## Outputs

```
docs/milestones/
├── roadmap.md               # Overview: phase/milestone table, ordering rationale, icebox
├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
├── phase2-milestones.md
└── phaseN-milestones.md
```

File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-milestones.md`). Milestones are numbered globally and consecutively across all phase files (`01`, `02`, …) — numbering never restarts per phase.

Use the structure in `template.md` for each phase file and for the roadmap.

## How to Slice Features

A well-sized feature:

- Delivers observable user value (or unblocks one that does)
- Touches one primary screen/flow (may touch shared components)
- Has 3–7 acceptance criteria
- Can be described in one sentence starting with a verb ("Edit user profile", "Filter tasks by tag")
- Works verbatim as a command argument: `/add-feature Edit user profile`

Too big (split it): "User management" → "Register account", "Log in / log out", "Edit user profile", "Reset password".
Too small (merge it): "Change button color" → fold into the feature that owns that screen.

## How to Group Milestones and Phases

1. Tag every feature with its PRD priority and its dependencies.
2. Milestone 1 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
4. **Phase 1** contains milestone 1 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
5. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.

## Status Tracking Rules

- Feature status lives **only** in the feature checkbox inside its phase file.
- Milestone status (`Not started` / `In progress` / `Completed`) lives in the milestone's section of the phase file **and** in the roadmap table — keep them in sync.
- Phase status lives in the phase file header **and** in the roadmap table.
- `/add-feature` Step 8 updates the feature checkbox; `/execute-milestones` additionally updates milestone and phase statuses and the roadmap pointers.
- Re-planning (adding/moving/removing features or milestones) must update both the affected phase file(s) and `roadmap.md` in the same change.

## Consistency Checklist

Before finishing:

- [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox).
- [ ] Every feature appears in exactly one milestone; every milestone in exactly one phase file.
- [ ] Milestone numbering is global and consecutive across phase files.
- [ ] No feature or milestone precedes one of its dependencies.
- [ ] Phase 1 delivers a usable end-to-end MVP on its own.
- [ ] Every feature has acceptance criteria and a ready-to-run `/add-feature` command line.
- [ ] Every phase file header has its ready-to-run `/execute-milestones` command line.
- [ ] `roadmap.md` table matches the phase files (names, counts, statuses).