---
prompt_version: 1
layer: milestone
action: build
---

# Prompt: Build Milestone Overview

Use the upstream phase and slice context to create or update a milestone overview.

## 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.
- Create missing canonical artifacts only for the selected layer. When revising an existing artifact, update it in place and do not create sibling, child, paired, or alternate artifacts unless the current user request explicitly asks for that creation step.
- Document a milestone-level purpose, scope, and acceptance criteria.
- Identify task candidates without over-specifying implementation.
- Default to `implement-*` task candidates when the milestone is expected to change code, runtime behavior, file outputs, or other executable repository behavior.
- Use `define` in milestone purpose, task candidates, or task slugs only for contract-setting work that creates or revises a durable boundary, schema, vocabulary, policy, rule, interface, or decision consumed by later work. If the deliverable is executable behavior, use `implement-*`; if it initializes an artifact or workspace shape, use `initialize-*` or `scaffold-*`; if it writes explanatory content, use `document-*`; if it captures evidence, use `record-*`.
- Do not use mixed task wording such as `implement or define`; choose the verb that owns the concrete deliverable before finalizing task candidates.
- In a generated milestone overview, `## Tasks` must declare at least one ordered task slug with a short description. Before link materialization, use raw backticked slug bullets such as ``- `01-implement-license-status-output`: implement human-readable and JSON license status reporting.``. After link materialization, the same declaration may be a Markdown link bullet such as `- [01-implement-license-status-output](tasks/01-implement-license-status-output/task-definition.md): implement human-readable and JSON license status reporting.`.
- Task slugs declared in milestone overviews must match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, be unique, and appear in ascending order.
- Do not leave prose-only task bullets or placeholder task text such as `To be planned.`, `TBD`, `TODO`, or `Pending.` in saved milestone overviews.
- Use a `document-*` task candidate only when later implementation would otherwise be blocked by a missing written contract, unresolved boundary, required shared decision, or evidence record that cannot safely be absorbed into the implementation task.
- Do not create repeated `document-*` lanes by default. Allow at most one supporting `document-*` task candidate per downstream implementation lane unless repository evidence shows multiple independent blockers with different target-path, validation, or rollback boundaries.
- Do not let a milestone intended to land executable behavior end with a documentation-only task list unless the milestone is explicitly documentation-only.
- Write task candidates so each candidate represents one coherent repository change that a standard implementation agent can complete, validate, and roll back independently.
- Give each task candidate one primary outcome and bounded likely target-path groups; do not bundle unrelated outcomes into the same candidate.
- Split task candidates when the work would require separate validation strategies, separate rollback paths, mixed readiness states, or more than one unresolved implementation decision.
- Merge trivial mechanical edits into a neighboring candidate when they have no meaningful behavioral, contract, validation, or artifact impact, unless sequencing or rollback isolation requires a separate candidate.
- Do not infer the target task count from nearby milestone examples, earlier milestones in the same phase, or a previously used decomposition pattern.
- Choose the minimum number of task candidates needed to fully implement the milestone purpose, acceptance criteria, dependencies, and validation focus without oversplitting.
- Do not add prose-only task candidates merely to elaborate inferred milestone detail; absorb that detail into the implementation-bearing task unless it is a real blocker.
- Treat task count as an outcome of decomposition rather than a planning convention; a milestone may legitimately need fewer or more task candidates when the sizing rules require it.
- Do not add a separate validation-only task candidate unless validation cannot be absorbed into the implementation-oriented task candidates without weakening scope clarity, reviewability, or rollback boundaries.
- Capture dependencies, risks, validation focus, and open questions.
- When revising an existing milestone overview, always refresh status, upstream traceability, and other front matter metadata so it reflects the current milestone state rather than the original draft state.
- Label assumptions explicitly instead of silently inventing scope, sequence, task decomposition, or validation detail.
- Preserve traceability to the phase, slice, and source spec.
- After creating or revising the milestone overview, run `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>` as read-only local trace-link evidence, then run `<day-shift-cli> link materialize --dry-run --artifact <milestone-overview-path>` and use `<day-shift-cli> link materialize --write --artifact <milestone-overview-path>` only when the dry-run reports safe selected-artifact body-reference changes. `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` may be used to check the `declared-child-slugs` lane for task declaration syntax; that lane accepts both raw backticked slug bullets and materialized Markdown-link slug bullets. Treat validation findings as evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as permission to mutate metadata, create tasks, or update reconciliation.
- Stop and report instead of guessing when the selected artifact and upstream evidence conflict materially.
- Preserve user-authored content when updating.
- Use repository-relative paths throughout the artifact.
- Preserve the canonical artifact-shape contract from `.day-shift/specs/06-templates-and-prompts/templates.md`: one visible H1, the required H2 section names in order, parser-safe `Open Questions` none-state, and no leaked scaffolding prose or unresolved placeholders in the saved artifact.

## Template Reference

Use `.day-shift/templates/milestone-overview.md` as the artifact shape.

## Required Output

Create or update a milestone overview artifact with the configured template sections and valid front matter.
