# Skill Test Spec: /milestone-review ## Skill Summary `/milestone-review` generates a comprehensive review of a completed milestone: what shipped, velocity metrics, deferred items, risks surfaced, and retrospective seeds. In full mode the PR-MILESTONE director gate runs after the review is compiled (producer reviews scope delivery). In lean and solo modes the gate is skipped. The skill asks "May I write to `production/milestones/review-milestone-N.md`?" before persisting. Verdicts: MILESTONE COMPLETE or MILESTONE INCOMPLETE. --- ## Static Assertions (Structural) Verified automatically by `/skill-test static` — no fixture needed. - [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools` - [ ] Has ≥2 phase headings - [ ] Contains verdict keywords: MILESTONE COMPLETE, MILESTONE INCOMPLETE - [ ] Contains "May I write" language (skill writes review document) - [ ] Has a next-step handoff (what to do after review is written) --- ## Director Gate Checks | Gate ID | Trigger condition | Mode guard | |---------------|--------------------------------|-------------------------| | PR-MILESTONE | After review document compiled | full only (not lean/solo) | --- ## Test Cases ### Case 1: Happy Path — Nearly complete milestone with one deferred story **Fixture:** - `production/milestones/milestone-03.md` exists with 8 stories - 7 stories have `Status: Complete` - 1 story has `Status: Deferred` (deferred to milestone-04) - `review-mode.txt` contains `full` **Input:** `/milestone-review milestone-03` **Expected behavior:** 1. Skill reads `milestone-03.md` and all referenced sprint files 2. Skill compiles: 7 shipped, 1 deferred; velocity; no blockers 3. Skill presents review draft to user 4. PR-MILESTONE gate invoked; producer approves 5. Skill asks "May I write to `production/milestones/review-milestone-03.md`?" 6. User approves; file is written; verdict MILESTONE COMPLETE **Assertions:** - [ ] Deferred story is noted in the review with its target milestone - [ ] Verdict is MILESTONE COMPLETE despite the one deferred story - [ ] PR-MILESTONE gate is invoked after draft compilation in full mode - [ ] Skill asks "May I write" before writing review file - [ ] Review document path matches `production/milestones/review-milestone-03.md` --- ### Case 2: Blocked Milestone — Multiple blocked stories **Fixture:** - `production/milestones/milestone-03.md` exists with 5 stories - 2 stories have `Status: Complete` - 3 stories have `Status: Blocked` (named blockers listed in each story) - `review-mode.txt` contains `full` **Input:** `/milestone-review milestone-03` **Expected behavior:** 1. Skill reads milestone and sprint files 2. Skill finds 3 blocked stories; compiles blocker details 3. Verdict is MILESTONE INCOMPLETE 4. PR-MILESTONE gate runs; producer notes the unresolved blockers 5. Review is written with blocker list on approval **Assertions:** - [ ] Verdict is MILESTONE INCOMPLETE when any stories are Blocked - [ ] Each blocked story's name and blocker reason is listed in the review - [ ] PR-MILESTONE gate is still invoked in full mode even for INCOMPLETE verdict - [ ] "May I write" prompt still appears before file write --- ### Case 3: Full Mode — PR-MILESTONE returns CONCERNS **Fixture:** - Milestone-03 has 6 complete stories but 2 were not in the original scope (added mid-sprint) - `review-mode.txt` contains `full` **Input:** `/milestone-review milestone-03` **Expected behavior:** 1. Skill compiles review; notes 2 out-of-scope stories shipped 2. PR-MILESTONE gate invoked; producer returns CONCERNS about scope drift 3. Skill surfaces the CONCERNS to the user and adds a "scope drift" note to the review 4. User approves revised review; file written as MILESTONE COMPLETE with caveat **Assertions:** - [ ] CONCERNS from PR-MILESTONE gate are shown to user before write - [ ] Scope drift is explicitly noted in the written review document - [ ] Verdict is MILESTONE COMPLETE (stories shipped) with CONCERNS annotation - [ ] Skill does not suppress gate feedback --- ### Case 4: Edge Case — No milestone file found for specified milestone **Fixture:** - User calls `/milestone-review milestone-07` - `production/milestones/milestone-07.md` does NOT exist **Input:** `/milestone-review milestone-07` **Expected behavior:** 1. Skill attempts to read `production/milestones/milestone-07.md` 2. File not found; skill outputs an error message 3. Skill suggests checking available milestones in `production/milestones/` 4. No gate is invoked; no file is written **Assertions:** - [ ] Skill does not crash when milestone file is absent - [ ] Output names the expected file path in the error message - [ ] Output suggests checking `production/milestones/` for valid milestone names - [ ] Verdict is BLOCKED (cannot review a non-existent milestone) --- ### Case 5: Lean/Solo Mode — PR-MILESTONE gate skipped **Fixture:** - `production/milestones/milestone-03.md` exists with 5 complete stories - `review-mode.txt` contains `solo` **Input:** `/milestone-review milestone-03` **Expected behavior:** 1. Skill reads review mode — determines `solo` 2. Skill compiles review draft 3. PR-MILESTONE gate is skipped; output notes "[PR-MILESTONE] skipped — Solo mode" 4. Skill asks user for direct approval of the review 5. User approves; review file is written; verdict MILESTONE COMPLETE **Assertions:** - [ ] PR-MILESTONE gate is NOT invoked in solo (or lean) mode - [ ] Skip is explicitly noted in skill output - [ ] User direct approval is still required before write - [ ] Verdict is MILESTONE COMPLETE after successful write --- ## Protocol Compliance - [ ] Shows compiled review draft before invoking PR-MILESTONE or asking to write - [ ] Always asks "May I write" before writing review document - [ ] PR-MILESTONE gate only runs in full mode - [ ] Skip message appears in lean and solo output - [ ] Verdict is MILESTONE COMPLETE or MILESTONE INCOMPLETE, stated clearly --- ## Coverage Notes - The case where the milestone has zero stories is not tested; it follows the MILESTONE INCOMPLETE pattern with a note suggesting the milestone may not have been planned. - Velocity calculation specifics (story points vs. story count) are not verified here; they are implementation details of the review compilation phase.