mpazaryna/orchestra-milestone

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