---
prompt_version: 2
layer: phase
action: review
---

# Prompt: Review Phase Overview

Review the selected phase overview for completeness and readiness to produce milestones, or compare it against milestone 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 phase 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 phase should not be treated as blocked merely because milestone artifacts or later implementation evidence have not been produced yet.
- For readiness review, verify that scope, acceptance criteria, dependencies, risks, validation focus, and open questions are clear.
- For readiness review, verify that milestone decomposition uses the minimum number of milestones needed to fully implement the phase and is justified by real acceptance, implementation, sequencing, validation, rollback, ownership, risk, or readiness boundaries.
- Verify that `## Milestones` uses ordered milestone slug declarations with short descriptions. Accept both raw backticked slug bullets such as ``- `01-license-payload-contract`: define signed payload parsing and canonicalization behavior.`` and materialized Markdown-link slug bullets such as `- [01-license-payload-contract](milestones/01-license-payload-contract/milestone-overview.md): define signed payload parsing and canonicalization behavior.`. In either representation, each link label or raw slug must match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, and declared milestone slugs must be unique and ascending.
- When child declaration syntax is in question, use `<day-shift-cli> validation smoke --scope planning --artifact <phase-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 milestone count appears over-split, prose-only, pattern-driven, or based on inferred detail that should remain in the phase overview.
- 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> phase review` as a findings-first surface over the selected phase overview plus milestone overviews and milestone reconciliation artifacts that exist beneath that phase.
- Treat `status` advancement after a completed evidence review as a separate explicit write step: use `<day-shift-cli> phase update --phase-overview <path> --field status=completed` for the phase overview and `<day-shift-cli> milestone update --milestone-overview <path> --field status=completed` for any stale milestone overviews.
- When the user explicitly authorizes phase-completion metadata writes after an evidence review, update the phase overview and every stale milestone overview whose completed reconciliation or task evidence makes the status transition deterministic; do not limit the administrative pass to the phase overview only.
- Keep the review read-only by default. Recommend mechanical metadata or artifact-hygiene follow-up commands when evidence is deterministic, but perform writes only when the current user request separately and explicitly asks for an update, sync, or administrative write action.
- For readiness review, check whether downstream milestone 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, slice overview, phase overview, workflow guidance, prompt contracts, templates, and downstream milestone artifacts before relying on earlier `implementation-summary.md` or reconciliation artifacts.
- Use prior summaries and reconciliation artifacts 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 phase overview, upstream planning artifacts, downstream milestone artifacts, workflow guidance, prompt contracts, and review findings to answer scope, dependency, validation-focus, metadata-transition, and downstream-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 phase, slice, 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 phase scope, milestone 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 phase overview against completed milestone evidence.
- For evidence review, emphasize whether milestone coverage and reconciliation evidence actually support the phase intent.
- For evidence review, detect stale milestone-level planning metadata that no longer matches completed milestone reconciliation or task evidence.
- Review output is read-only guidance unless a separate explicit update, sync, or write request applies. It may recommend candidate future phases, milestones, tasks, or metadata commands, but it must not create or mutate artifacts.
- Treat trace-link lifecycle disposition findings as phase evidence only. Phase review may report retired, deleted, migrated, malformed-storage, or applied-migration validation evidence and recommend a separate `link disposition preview` or migrated-only `link disposition apply` command, but it must not repair links, infer replacement targets, rewrite unsupported body references, mutate disposition storage, or treat retired/deleted dispositions as rewrite instructions.
- Planning artifacts and evidence files may be untracked while active work is in progress. Treat untracked task, milestone, phase, slice, source, or test evidence as an administrative handoff risk only when git state matters for review, commit readiness, or preservation; do not treat `git status` `??` output alone as missing acceptance evidence.
- Do not treat `move downstream`, `plan next work`, `identify follow-up work`, or `suggest next step` as permission to scaffold child artifacts during review. Report the proposed next planning structure and stop unless the user separately invokes the matching `next` prompt or an explicit create/scaffold command.
- Do not recommend scaffolding later declared phases or milestones ahead of incomplete earlier siblings unless the review records an explicit user-requested skip-ahead exception.
- Check that the phase does not contain task-level implementation details.
- Confirm upstream traceability.
- Check that front matter matches the body, especially status and any upstream traceability changes.
- After milestone reconciliation exists, check whether each reviewed milestone overview still carries stale metadata such as `status: draft` despite unambiguous completion evidence.
- 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.
- List stale milestone metadata as a metadata-hygiene or administrative follow-up item when the evidence is clear, and recommend the exact explicit overview update command when the next write is deterministic.
- 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 evidence and missing phase-level planning clarity. Only missing planning clarity should block the next planning instruction.
- Do not silently absorb newly discovered work into the current phase; record it as follow-up planning, discovered work, or backlog work instead.
- Identify whether milestone planning can proceed when milestone work has not started yet.
- Identify whether any milestone candidates should be merged or split because the current count is not decomposition-driven.
- Identify any phase-purpose, scope, acceptance-criteria, dependency, risk, validation-focus, or open-question gaps that remain after milestone work.
- 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 phase-level planning is still needed before creating milestones
- what metadata updates should be made before the next planning instruction
- 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
