Milestone Review

!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 copied from /sprint-plan's emitted headings — keep them in sync with it, not with what a milestone review wishes existed. The previous pattern asked for Summary|Goal|Velocity|Completed|Blockers| Retrospective, none of which /sprint-plan writes (it emits ## Sprint Goal, not ## Goal). Only Carryover matched — and that was the trap: a non-zero match count meant the zero-match escape hatch below could never fire, so every milestone review silently aggregated carryover tables and nothing else 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.