/milestone-review

name: milestone-review
description: "Milestone progress review — completeness, quality metrics, risk, go/no-go recommendation. At checkpoints or before a deadline."
argument-hint: "[milestone-name|current] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/milestone-review/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow`

Resolved above — use as-is; `--review` overrides `review_mode` for this run. No block → defaults in `.claude/docs/config-resolution.md`.

Milestone Review

Insufficient input — check this before producing any report

**If the inputs this skill needs do not exist, the answer is "could not run" — not a filled-in report.** Check first, and stop if the check fails.

1. List the inputs this skill reads (data files, prior reports, profiler output, test results, registries, source code). 2. For each, record `FOUND` or `ABSENT` — not "assumed present". 3. If any input required for a section is ABSENT, that section is **`NOT ASSESSED — NO DATA`**. Do not estimate it, do not infer it from an adjacent artifact, and do not leave a mandated cell to be filled by whoever reads the template next. 4. If **every** required input is ABSENT, stop and report **`NOT ASSESSED — NO DATA`** as the whole verdict, naming what was missing and which skill produces it.

**A verdict of `NOT ASSESSED` is a success.** It is the correct, useful answer to "what does the data say?" when there is no data. The failure mode this prevents is specific: a report whose verdict enum has no "could not run" state produces **false clean passes** — an asset audit returning COMPLIANT on a project with no assets and no standards, or a performance profile reporting ">99% headroom against a 16.67ms budget" with zero profiler data and no budget ever set.

**Absence of evidence is never evidence of absence.** A scan that finds no matches because there are no files to scan has not verified anything. Say which of the two happened — a reader cannot tell from a green result.

---

Phase 0: Parse Arguments

Extract the milestone name (`current` or a specific name).

See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

---

Phase 1: Load Milestone Data

Read the milestone definition from `production/milestones/` if it exists. If the argument is `current`, use the most recently modified milestone file.

> **No skill writes `production/milestones/`** — definitions are authored by hand > from `.claude/docs/templates/milestone-definition.md`, so most projects have > none. When the directory is absent or empty, say so and review against the > sprint reports alone; do not fabricate a definition. Take care with `current`: > this skill writes its own output as `[milestone-name]-review.md`, so a > most-recently-modified match can be a previous *review* rather than a > definition. Skip files ending `-review.md` when selecting.

Gather the sprint reports for sprints within this milestone from `production/sprints/`. Establish the denominator (glob them, count **N**), then scan the sections a milestone review actually aggregates rather than reading each report whole:

Grep pattern="^## (Sprint Goal|Capacity|Tasks|Carryover|Risks|Progress|Burndown Assessment|Emerging Risks|Definition of Done)" glob="production/sprints/sprint-*.md" output_mode="content" -A 12

> **These alternates are the headings `/sprint-plan` emits** (`## Sprint Goal`, > not `## Goal`) — not what a milestone review might expect. A pattern that > matches only one real heading still returns a non-zero count, so the > zero-match escape hatch below never fires and the review aggregates a fraction > of each report while reporting full coverage.

Full-read a single sprint report when its scanned sections point outside themselves, or when it matched nothing — a zero-match report predates the template and must be read, never silently dropped from the milestone's history. Report any sprint that contributed nothing: a milestone summary that quietly omits a sprint understates the work and the slippage both.

**Blocked stories** — the Blocked table and the blocked story count passed to PR-MILESTONE — are not in the sprint reports' scanned sections. Read them where they are recorded: the `status: blocked` stories in `production/sprint-status.yaml` (with their `blocker` field) and, for stories outside that sprint, one grep:

Grep pattern="^> \*\*Status\*\*: Blocked|BLOCKED:" glob="production/epics/**/story-*.md" output_mode="content"

Each blocked story goes in the Blocked table under the feature its epic folder implements, with its blocker (the yaml `blocker` field or the story's `BLOCKED:` note). With no story files and no `sprint-status.yaml`, the Blocked table and the blocked story count are `NOT ASSESSED — NO DATA`, not zero.

---

Phase 2: Scan Codebase Health

• Scan for `TODO`, `FIXME`, `HACK` markers that indicate incomplete work
• Count open bugs by severity for Quality Metrics from `production/qa/bugs/` (one grep of the `**Severity**` and `**Status**` lines, as `/bug-triage` does); with no bug files, the bug lines are `NOT ASSESSED — NO DATA`, not zero
• Check the risk register at `production/risk-register/` if it exists (hand-authored from `.claude/docs/templates/risk-register-entry.md`; no skill writes it, so absence is normal — note it rather than skipping risk assessment silently)

---

Phase 3: Generate the Milestone Review