milestone-review

name	milestone-review
description	Review a completed milestone, update the build plan with actuals, and adjust future milestones based on learnings
invocation	user
user_invocation	/milestone-review

Milestone Review Skill

You are reviewing a completed milestone and updating the project plan to reflect reality. This is the self-improvement loop that keeps the build plan accurate.

Execution

Step 1: Gather Data

1. Read docs/BUILD-PLAN.md — find the milestone being reviewed
2. Read the git log for the milestone branch: git log --oneline feat/M{X}.{Y}*
3. Count files created/modified: git diff --stat main...HEAD (or similar)
4. Check test results: bun test
5. Check for any TODO/FIXME/HACK comments in new code: grep -rn "TODO\|FIXME\|HACK" packages/

Step 2: Update Milestone Entry

Edit the milestone in docs/BUILD-PLAN.md. Add an ### Actual Outcome section:

### Actual Outcome

**Status:** ✅ Complete | 🚧 Partial | ⛔ Blocked
**Time:** {X days} (estimated: {Y days})
**Velocity:** {X/Y ratio}

**Delivered:**
- [x] {deliverable 1}
- [x] {deliverable 2}
- [ ] {deferred item} → moved to M{A}.{B}

**Blockers:**
- {blocker description and resolution}

**Learnings:**
- {technical insight that affects future work}
- {estimate adjustment rationale}

**Tech Debt Added:**
- {any shortcuts taken, with cleanup target milestone}

**Decisions Made:**
- {key decisions, reference ADR if created}

Step 3: Adjust Future Milestones

Based on the velocity ratio and learnings:

1. Re-estimate upcoming milestones. If velocity is consistently 0.7x, inflate remaining estimates by ~1.4x
2. Move deferred items to the appropriate future milestone
3. Add new milestones if scope was discovered during implementation
4. Update dependencies if the critical path changed
5. Flag risks for upcoming milestones based on what was learned

Step 4: Update Project Configuration

Check if any of these need updating:

• CLAUDE.md — new commands, conventions, or patterns
• .claude/settings.json — new guardrails needed
• .claude/agents/*.md — agent instructions need refinement
• packages/shared/src/db/schema.ts — schema evolved

Step 5: Velocity Dashboard

Update the velocity tracking section at the bottom of docs/BUILD-PLAN.md:

## Velocity Tracker

| Milestone | Estimated | Actual | Velocity | Notes |
|-----------|-----------|--------|----------|-------|
| M0.1 | 3 days | 2 days | 1.5x | Scaffolding was fast |
| M0.2 | 3 days | 4 days | 0.75x | Schema iteration took longer |
| ... | ... | ... | ... | ... |

**Rolling average velocity:** {X}x
**Adjusted weeks remaining:** {calculated from remaining milestones / velocity}

Step 6: Next Milestone Recommendation

Based on the dependency graph and current state, recommend which milestone to tackle next:

## Recommended Next: M{X}.{Y} — {Title}

**Why:** {rationale — dependencies met, critical path, or quick win}
**Prerequisites:** All met ✅
**Estimated time:** {adjusted estimate based on velocity}
**Key risk:** {if any}

Constraints

• Never delete historical entries — only append outcomes
• Be honest about velocity — overestimation causes downstream pain
• If velocity is consistently below 0.5x for agent-generated code, note which task types need more human involvement
• Architecture decisions that affect multiple milestones → create an ADR in docs/decisions/