---
name: milestone-execution
description: Guide for executing one phase file (phaseN-milestones.md) - implementing its milestones one by one, with a separate steering directory per milestone, features divided into tasks, and gate criteria between milestones. Use when running /execute-milestones or implementing a whole milestone in one run.
allowed-tools: Read, Write, Edit, Bash
---

# Milestone Execution Skill

This skill explains how to execute **one phase file** (`docs/milestones/phase[N]-milestones.md`) — implementing its milestones one at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory, and a `/execute-milestones` run covers exactly the milestones of the given phase file, strictly in order.

## Core Principles

1. **One phase file per run**: `/execute-milestones` always operates on an explicitly specified phase file — never on "everything". The next phase requires a new run with the next file.
2. **One milestone = one steering directory**: every milestone gets its own `.steering/[YYYYMMDD]-milestone-[NN]-[name]/` with its own `requirements.md`, `design.md`, and `tasklist.md`. Documents are never shared or reused between milestones.
3. **Strict order, one at a time**: milestones execute in ascending number within the phase file. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
4. **Features divided into tasks**: the milestone's features (from its section in the phase file) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The phase file stays the "what"; the steering tasklist is the "how".
5. **Same discipline as `/add-feature`**: the steering skill's implementation mode, the development guidelines, the validator subagent, and the test loop all apply per milestone.
6. **Status flows upward**: task status lives in the steering `tasklist.md`; feature, milestone, and phase status live in the phase file and `roadmap.md`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer; when the phase's last milestone completes, mark the phase `Completed` and point the roadmap at the next phase file.

## Steering Directory per Milestone

Naming: `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` (e.g. `.steering/20260702-milestone-01-mvp/`).

### `requirements.md`
- Milestone goal (from the milestone's section in the phase file)
- In/out of scope
- One section per feature: description, related PRD requirements, affected screens, acceptance criteria
- The milestone's Definition of Done

### `design.md`
- Implementation approach across the whole milestone
- Shared components and data-model changes used by multiple features (build these first)
- Feature implementation order within the milestone, with a one-line rationale
- Consistency notes against `docs/architecture.md` and `docs/design/ui-blueprint.json`

### `tasklist.md`
Tasks are **grouped by feature**, in the implementation order chosen in `design.md`:

```markdown
# Tasklist: Milestone 01 — MVP

## Shared Foundations
- [ ] [Task that multiple features depend on, e.g. data model, shared component]

## Feature: Register account
- [ ] [Task 1: data/model layer]
- [ ] [Task 2: logic/service layer]
- [ ] [Task 3: UI per affected screen]
- [ ] [Task 4: tests for the acceptance criteria]

## Feature: Log in / log out
- [ ] ...

## Milestone Verification
- [ ] All acceptance criteria in requirements.md confirmed
- [ ] npm test / lint / typecheck pass

## Post-Implementation Retrospective
_Filled at the end: completion date, plan vs. actual, lessons learned._
```

## How to Divide a Feature into Tasks

- 3–8 tasks per feature; each completable in **one implementation-loop iteration**.
- Slice along the natural layers the feature touches: data/model → logic/service → UI (one task per affected screen) → tests.
- Every feature's section ends with a task that verifies its acceptance criteria.
- Tasks that unblock several features go into a "Shared Foundations" section at the top — never duplicated per feature.

## Gate Criteria Between Milestones

A milestone passes its gate only when **all** of the following hold. Only then may the next milestone start:

- [ ] Every task in the milestone's `tasklist.md` is `[x]` (or struck with a technical reason).
- [ ] The `implementation-validator` subagent's validation passed.
- [ ] `npm test`, `npm run lint`, `npm run typecheck` all succeed.
- [ ] The six persistent documents in `docs/` are reconciled with the milestone's changes.
- [ ] In the phase file: every feature of the milestone is checked off, and the milestone status is `Completed` with Completion Notes.
- [ ] `roadmap.md` points to the next milestone (or, after the phase's last milestone, the phase is `Completed` and the roadmap points to the next phase file).

## Failure Handling

- **A task fails repeatedly**: split it (exception rule A) or re-approach via `design.md`; do not skip it.
- **A feature turns out to be unimplementable as specified**: update the phase file and `requirements.md` with the revised scope and reason, then continue — the plan must reflect reality.
- **An external blocker stops the milestone** (missing credential, unavailable service, a decision only the user can make): record the blocker in the milestone's `tasklist.md`, in the phase file, and in `roadmap.md` (status stays `In progress`), then stop and report. This is the **only** permitted early stop; never silently skip to the next milestone, because later milestones depend on earlier ones.

## Consistency Checklist

Before declaring a milestone (or the whole run) complete:

- [ ] Each executed milestone has exactly one steering directory, named `[date]-milestone-[NN]-[name]`.
- [ ] Every feature of the milestone appears as a section in that `tasklist.md`.
- [ ] Feature checkboxes in the phase file match the completed work.
- [ ] Milestone and phase statuses in the phase file match `roadmap.md`, and the roadmap pointers are correct.
- [ ] No task or feature from a later milestone or a later phase file was implemented early.