Authoring Milestones
The mental model
A milestone is a versioned release boundary — it groups features and flows into a coherent unit that ships together. It answers: “What does this release contain, when does it ship, and what is its purpose?”
Milestones are a planning tool, not a project management system. They communicate scope and intent, not task assignments or sprint velocity.
What milestones contain
A milestone has three essential elements:
- Identity — a name, a target release date, and a status (
planned,in-progress,done) - Purpose — a
{% tldr %}explaining what this release achieves and why it matters - Scope — a set of
{% includes %}references pointing to features and flows
{% includes ref="feature/add-bookmark" /%}{% includes ref="feature/remove-bookmark" /%}{% includes ref="flow/add-bookmark" /%}The includes references create bidirectional links: the milestone page shows what it contains, and each feature/flow page shows which milestones reference it.
Deciding what ships together
Good milestone scoping asks:
- “Can a user get value from this set of features alone?” — a milestone should be independently useful
- “Do these features depend on each other?” — co-dependent features should ship together
- “Is the scope achievable in the target timeframe?” — over-stuffed milestones slip
The ideal milestone is the smallest set of features that delivers a coherent experience. It is better to ship three focused milestones than one sprawling one.
Relationship to other document types
- Features — milestones include features; features do not know about milestones
- Flows — milestones can include flows when a specific interaction is release-critical
- Stories — stories may span milestones (a journey imagined early may only be completable in a later release)
- Domains — milestones do not directly reference domains; the relationship is implicit through features
Status lifecycle
Milestones move through three states:
- planned — scope is defined, work has not started
- in-progress — active development underway
- done — shipped and closed
Update status as work progresses. A milestone stuck in planned with a past release date is a signal that scope needs revisiting.
Writing the TLDR
The milestone’s TLDR should communicate:
- What this release enables (in user terms, not technical terms)
- Why this grouping matters (strategic rationale)
Good: “The first shippable version — users can save, organize, and retrieve bookmarks across devices.”
Weak: “Implements features 1-5.”
Common mistakes
| Mistake | Why it hurts |
|---|---|
| Milestone per feature | If every feature gets its own milestone, you have no meaningful grouping. Milestones exist to show what ships together. |
| No clear scope | A milestone without includes references is just a date on a calendar. It communicates nothing about what is planned. |
| Scope creep without update | Adding features without updating the milestone document creates drift between plan and reality. |
| Past dates, still “planned” | Stale milestones erode trust in the spec. Update or revise when dates slip. |
| Too large | A milestone with 20 features is not a release plan — it is a wish list. Keep scope tight. |
| Missing TLDR | Without a purpose statement, readers cannot evaluate whether the scope makes sense. |
Evolution
Milestones are the most mutable document type. Scope changes as priorities shift, dates move as reality intervenes, and new milestones are added as the roadmap extends. When a milestone is done, keep it in the spec as historical record — it documents what shipped and when.
When features slip from one milestone to another, update both documents. The spec should always reflect current intent, not original plan.