mpazaryna Milestone Review
Read the active milestone PRD, compare its materials table against actual repo state, and surface what needs attention. Also performs a reverse check — scanning for work items in .orchestra/work/ that don't appear in any milestone, catching scope drift before it compounds.
Steps
1. Find the Active Milestone
- Read
.orchestra/roadmap.md - Parse the materials table
- Find the first milestone with status "In Progress" or "Not Started"
- If $ARGUMENTS specifies a milestone name, use that instead
- Read the milestone's PRD at the path in the materials table
2. Audit the Materials Table
For each row in the milestone PRD's materials table:
If location is a file path:
- Check if the file exists
- If it exists, read it and assess completeness
- Compare actual state to the status column — flag mismatches
If location is an issue tracker link:
- Note it for the user and skip — link resolution requires an installed integration
If status is "Done":
- Verify the deliverable actually exists and looks complete
If status is "Not Started" or "Needs Refresh":
- This is a gap — candidate for new work
3. Reverse Check — Orphaned Work Items
The forward check (step 2) asks: "what's in the milestone but missing from the repo?" The reverse check asks: "what's in the repo but missing from any milestone?"
- Glob
.orchestra/work/*/to list all work item folders - For every milestone in
roadmap.md, read its PRD and collect all file paths from its materials table - Build the union of all tracked paths across all milestones
- For each work item folder, check whether any file in it appears in that union
- Any folder with no tracked entry is orphaned — work that exists without a stated goal
Orphaned work items are a velocity smell: work that moved faster than the roadmap. They are not a blocker, but they should be surfaced so the human can assign them to a milestone or acknowledge them as one-off work.
4. Present the Review
## Milestone Review: {milestone name}
**Objective:** {from PRD}
**Progress:** {N}/{M} deliverables done
### Gaps (work needed)
| Material | Status | Issue |
|----------|--------|-------|
| {name} | Not Started | {why it matters} |
| {name} | Needs Refresh | {what changed since last version} |
### Stale (status says done but reality differs)
| Material | Claimed | Actual |
|----------|---------|--------|
| {name} | Done | {what's actually wrong} |
### On Track
| Material | Status |
|----------|--------|
| {name} | Done |
| {name} | In Progress |
### Orphaned Work Items (in repo, not in any milestone)
| Work Item | Status | Action |
|-----------|--------|--------|
| {path} | {spec status} | Assign to a milestone or acknowledge as one-off |
### Recommended Next Actions
1. {highest priority gap — why}
2. {second priority — why}
3. {third — why}
If no orphaned items exist, omit that section from the report.
5. Propose Work
For each gap, suggest whether it needs:
- A PRD (if scope is unclear or multi-deliverable)
- A spec (if approach needs defining)
- A ticket (if ready to execute)
- Direct work (if small enough to just do)
For each orphaned item, suggest: assign to an existing milestone, create a new milestone, or acknowledge as intentional one-off work.
Rules
- Read-only — don't modify any files
- Be honest about mismatches — if status says "Done" but the file is empty, flag it
- Trace everything back to the roadmap — gaps should connect to the milestone objective