---
prompt_version: 1
layer: milestone
action: review
---

# Prompt: Review Milestone Overview

Review the selected milestone overview for completeness and readiness to produce task definitions, or compare it against task and reconciliation evidence when downstream work already exists.

## Instructions

- Command placeholder: Expand `<day-shift-cli>` to the resolved session invocation. Use `day-shift` for installed/user mode after verification, and use `node dist/cli/index.js` in repository development mode when compiled `dist` output is current.
- For readiness review, determine whether the milestone is ready for the next planning instruction, not only whether its current metadata already says so.
- For readiness review, evaluate planning readiness rather than downstream completion. A milestone should not be treated as blocked merely because child task definitions, implementation artifacts, or reconciliation evidence have not been produced yet.
- For readiness review, verify acceptance criteria, scope, task candidates, dependencies, risks, and validation focus.
- For readiness review, verify that the milestone's task decomposition is justified by the milestone's own purpose, acceptance criteria, dependencies, and validation focus rather than inherited from nearby milestone examples or an earlier counting pattern.
- For readiness review, verify that task decomposition uses the minimum number of tasks needed to fully implement the milestone and is justified by real implementation, sequencing, validation, rollback, ownership, risk, or readiness boundaries.
- Verify that `## Tasks` uses ordered task slug declarations with short descriptions. Accept both raw backticked slug bullets such as ``- `01-implement-license-status-output`: implement human-readable and JSON license status reporting.`` and materialized Markdown-link slug bullets such as `- [01-implement-license-status-output](tasks/01-implement-license-status-output/task-definition.md): implement human-readable and JSON license status reporting.`. In either representation, each link label or raw slug must match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, and declared task slugs must be unique and ascending.
- When child declaration syntax is in question, use `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` and inspect the `declared-child-slugs` lane as read-only evidence; that lane accepts both raw backticked slug bullets and materialized Markdown-link slug bullets.
- Flag a warning when task count appears to follow a repeated convention without milestone-specific justification, including unexplained reuse of a prior three-task or four-task shape.
- Flag a warning when task candidates are prose-only or based on inferred detail that should be absorbed into an implementation-bearing task.
- Flag a warning when `define` is used as an action verb without clearly naming a contract, boundary, schema, vocabulary, policy, rule, interface, or decision deliverable. If the intended work is initialization, implementation, documentation, evidence capture, review, or validation, recommend the more specific verb.
- Treat `<day-shift-cli> milestone review` as a read-only findings surface over the selected milestone overview plus completed task summaries and milestone reconciliation state when available.
- For readiness review, check whether downstream task and reconciliation evidence has already resolved prior open questions, reduced uncertainty, or filled earlier planning gaps.
- When both are available, prefer direct source surfaces over prior summaries when resolving readiness questions: use the current spec, phase overview, milestone overview, workflow guidance, prompt contracts, templates, task definitions, and reconciliation files before relying on earlier `implementation-summary.md` or reconciliation summaries alone.
- Use prior summaries as supporting evidence for what was previously changed or decided, not as the strongest proof of the current repository contract when the underlying source surfaces are already available locally.
- For readiness review, resolve recurring planning questions from existing repository evidence before escalating them: use the milestone overview, upstream planning artifacts, task definitions, completed implementation summaries, workflow guidance, prompt contracts, and review findings to answer task-selection, validation-shape, metadata-transition, and review-handoff questions whenever those surfaces already establish the default.
- For readiness review, prefer contract-based default answers over open-ended human prompts when the repo already defines the boundary. If the milestone, phase, or workflow clearly establishes the expected planning lane, record that answer directly instead of asking the user to restate it.
- When more than one interpretation is possible, escalate only if the choice would materially change milestone scope, task decomposition, or produce conflicting writes. If one interpretation is clearly favored by declared scope plus repository contracts, state that assumption explicitly and treat it as resolved review guidance rather than a pending human decision.
- For evidence review, compare the milestone overview against completed task and reconciliation evidence.
- For evidence review, emphasize whether completed task evidence and reconciliation state actually support the milestone intent.
- Review output is read-only guidance unless a separate explicit update, sync, or write request applies. It may recommend candidate tasks, follow-up planning, or metadata commands, but it must not create or mutate artifacts.
- Do not treat `move downstream`, `plan next work`, `identify follow-up work`, or `suggest next step` as permission to scaffold task artifacts during review. Report the proposed next task structure and stop unless the user separately invokes the matching `next` prompt or an explicit create/scaffold command.
- Do not recommend scaffolding later declared tasks ahead of incomplete earlier siblings unless the review records an explicit user-requested skip-ahead exception.
- Check that the milestone has not drifted into step-by-step implementation.
- Confirm upstream traceability.
- Check that front matter matches the body, especially status and any upstream traceability changes.
- If the body is ready for the next planning step but the front matter has not yet been updated to reflect the available evidence, treat that as a metadata-update recommendation rather than an automatic planning blocker.
- Treat stale metadata as a blocking issue only when it creates real ambiguity about whether downstream planning should proceed, or when the body still lacks enough evidence to justify advancing the metadata.
- When stale milestone metadata is unambiguous, recommend the exact explicit update command instead of updating metadata during review.
- Do not perform metadata-hygiene or administrative follow-up merely because it is mechanical; report it under `Metadata-Hygiene Follow-Ups`, `Administrative Follow-Ups`, or `Metadata Updates Needed`.
- For readiness review, distinguish between missing downstream execution evidence and missing milestone-level planning clarity. Only missing planning clarity should block the next planning instruction.
- Do not silently absorb newly discovered work into the current milestone; record it as follow-up planning, discovered work, or backlog work instead.
- Identify which task should be created next and why when task planning has not started yet.
- Identify whether any task candidates should be merged or split because the current count looks pattern-driven rather than decomposition-driven.
- Flag a warning when a milestone falls into repeated `document-*` lanes ahead of one implementation outcome without milestone-specific evidence that more than one independent blocker exists.
- Identify any milestone-purpose, scope, acceptance-criteria, validation-focus, or open-question gaps that remain after implementation evidence exists.
- Keep findings separated between blockers, warnings, and metadata-hygiene follow-ups; do not collapse the review into automatic acceptance or metadata mutation.
- Treat `User Decisions Needed` as a narrow exception output. Use it only for genuine external choices such as product intent, priority tradeoffs, reviewer-policy decisions, or materially conflicting evidence that cannot be resolved from repository context. Do not put ordinary contract interpretation, metadata advancement recommendations, next-step guidance, or purely mechanical metadata-hygiene or administrative cleanup there.

## Required Output

Return findings grouped as:

- Blocking Issues
- Missing Evidence
- Warnings
- Review Mode
- Next Planning Recommendation, if this is a readiness review
- Metadata Updates Needed, if this is a readiness review and the evidence supports advancing status or planning metadata
- Satisfaction Status, if this is an evidence review
- Metadata-Hygiene Follow-Ups
- Administrative Follow-Ups
- User Decisions Needed
- Suggested Next Step

For readiness review, explicitly state:

- whether open questions are now resolved by downstream evidence
- whether more milestone-level planning or task decomposition is still needed
- what metadata updates should be made before the next planning instruction
- which task should be created next and why when the milestone is otherwise ready to proceed
- whether any cited gap is a true pre-planning blocker or only expected downstream evidence
- whether any previously open planning question was answered from repository contracts or existing evidence without requiring new human input
