# Planning Layers Reference

This reference is the compact responsibility map for Day Shift planning layers. It is documentation-only and does not change planning algorithms, scaffold destinations, metadata behavior, or review eligibility.

## Layer Sequence

Standard planning flows from specification to slice, phase, milestone, task definition, implementation summary, and milestone reconciliation.

```text
specification -> slice overview -> phase overview -> milestone overview -> task definition -> implementation summary -> milestone reconciliation
```

Lightweight planning may skip phases and milestones only when the selected slice explicitly remains low-risk and implementation-sized.

Review, validation, inventory, and navigation commands provide evidence about these layers. They do not create, repair, advance, or reconcile artifacts unless a separate write-capable workflow or command is explicitly invoked.

## Specification

Specifications describe source intent and are registered through `.day-shift/specs/index.json`. They may be external references or repo-local Markdown files.

- Producers: human operators, product or engineering planning sources, and recertification work that captures or refreshes source intent.
- Primary consumers: spec selection commands, slice planning, planning inventories, and downstream traceability checks.
- Parent dependencies: none inside the Day Shift planning hierarchy; external source material may remain the originating reference.
- Child dependencies: slice overviews consume registered specification identity, source references, intended planning depth, implementation order, and destination context.
- Downstream usage: specifications define why work exists, what is in scope, what is out of scope, and which outcomes downstream planning must preserve.
- Expected outputs: a registered spec entry and, when the source is repo-local, a specification Markdown artifact with one visible title, source metadata, goals, scope, non-goals, requirements, and acceptance criteria.
- Evidence handoff: downstream planning artifacts preserve source traceability through `upstream.specs` and should point readers back to the selected source spec instead of replacing source intent with status summaries.

## Slice Overview

Slice overviews group implementation order and scope. They declare downstream phases for standard planning or direct tasks for lightweight planning.

- Producers: the specification-to-slice planning workflow after a registered source spec is selected and any needed recertification is complete.
- Primary consumers: phase planning, lightweight task planning, workflow navigation, validation, and documentation that needs the slice-level boundary.
- Parent dependencies: registered specification metadata and source-spec content.
- Child dependencies: standard slices declare ordered phase slugs; lightweight slices may declare direct task slugs when the lightweight boundary still holds.
- Downstream usage: the slice overview sets the implementation lane, desired outcome, major scope boundaries, planning depth, decisions, risks, and validation strategy for all child planning work.
- Expected outputs: `.day-shift/planning/<order>-<slice>/slice-overview.md` plus stable slice holding areas such as `decisions/` and `notes/` when scaffolded by the standard workflow. Existing `overview.md` slice artifacts remain supported legacy evidence while the migration is in progress.
- Evidence handoff: phase or lightweight task artifacts carry `upstream.slice_overview` so later implementation evidence can be traced back to the slice boundary.

## Phase Overview

Phase overviews group major work inside a slice and declare milestones in implementation order.

- Producers: the slice-to-phase planning workflow from a standard slice overview.
- Primary consumers: milestone planning, phase review, workflow navigation, and later documentation cleanup that needs phase-level grouping.
- Parent dependencies: the parent slice overview, its source-spec traceability, and the ordered phase declaration in the slice.
- Child dependencies: phase overviews declare ordered milestone slugs with enough context to size acceptance checkpoints.
- Downstream usage: phases separate major work streams while preserving one slice-level intent, making milestone sequencing and reference or workflow cleanup boundaries explicit.
- Expected outputs: `.day-shift/planning/<order>-<slice>/phases/<phase>/phase-overview.md` with purpose, scope, declared milestones, acceptance criteria, dependencies, risks, validation focus, and open questions.
- Evidence handoff: milestone overviews carry `upstream.phase_overview`, while phase review later reads milestone and reconciliation evidence without replacing those artifacts.

## Milestone Overview

Milestone overviews define an acceptance checkpoint and declare implementation-sized tasks. Milestone reconciliation remains pending until every task summary is complete.

- Producers: the phase-to-milestone planning workflow from a standard phase overview.
- Primary consumers: task planning, task execution ordering, milestone reconciliation, milestone review, and downstream workflow handoff cleanup.
- Parent dependencies: the parent phase overview, inherited source-spec and slice traceability, and the ordered milestone declaration in the phase.
- Child dependencies: milestone overviews declare ordered task slugs and preserve a milestone-level reconciliation placeholder as the default later rollup path.
- Downstream usage: the milestone defines the review checkpoint that tasks collectively satisfy. It is the source of truth for declared task order, milestone intent, acceptance criteria, dependencies, risks, and validation focus.
- Expected outputs: a milestone `milestone-overview.md`, a pending milestone `reconciliation.md`, and later a `tasks/` directory containing only declared task workspaces.
- Evidence handoff: task definitions carry `upstream.milestone_overview`; completed implementation summaries later feed milestone reconciliation.

## Task Definition

Task definitions are the source of truth for one implementation task's objective, target paths, acceptance criteria, dependencies, constraints, validation, and closeout expectations.

- Producers: the milestone-to-task planning workflow from a milestone overview, followed by contract completion when scaffolding initially creates placeholders.
- Primary consumers: task implementation agents, read-only readiness review, implementation-summary build and review, task review, and milestone reconciliation.
- Parent dependencies: the parent milestone overview, concrete dependency artifacts named by the task, and any earlier sibling task outputs required before implementation.
- Child dependencies: the paired implementation summary in the same task directory is the required execution-evidence artifact.
- Downstream usage: the task definition bounds implementation scope, target paths, validation commands, rollback expectations, assumptions, and open questions for one independently closable change.
- Expected outputs: `tasks/<task-slug>/task-definition.md` with implementation-ready scope and a paired `implementation-summary.md` initialized as pending before work starts.
- Evidence handoff: the paired implementation summary records what actually changed and whether the task satisfied the definition; the task definition remains the planning contract rather than the execution record.

## Implementation Summary

Implementation summaries are paired task-local execution artifacts. They record changed paths, validation, acceptance results, deviations, discovered work, follow-up work, and review evidence.

- Producers: the task implementation lifecycle after scoped work and validation have been performed.
- Primary consumers: read-only implementation-summary review, task review, milestone reconciliation, later phase or slice review, and future agents deciding whether work is complete.
- Parent dependencies: the paired task definition, scoped implementation changes, validation output, and any accepted deviations or discovered work from execution.
- Child dependencies: milestone reconciliation consumes completed implementation summaries; task-level reconciliation is an explicit exception, not the default child layer.
- Downstream usage: implementation summaries are the task-local evidence handoff. They tell reviewers which paths changed, which criteria passed or were deferred, which validation ran, and what follow-up remains.
- Expected outputs: `implementation-summary.md` with `implementation_status: completed`, `status: completed`, changed paths, acceptance results, validation evidence, scope classification, deviations, risks or follow-ups, and open questions.
- Evidence handoff: milestone reconciliation is eligible only after every declared task has a completed, non-placeholder implementation summary. Status fields alone are insufficient without body evidence.
- Metadata ownership: apply CLI-supported lifecycle metadata transitions through the matching update or sync command instead of inferring and hand-editing front matter.

## Reconciliation

Milestone reconciliation reviews completed task summaries against the milestone acceptance criteria. It records the deduped milestone verdict, validation review, discovered work, backlog work, accepted residual work, follow-up tasks, and review concerns.

- Producers: the implementation-to-reconciliation workflow after all declared task summaries under the milestone are completed and non-placeholder.
- Primary consumers: milestone review, phase review, slice-level rollup, structural-pressure sync when applicable, and follow-up planning.
- Parent dependencies: the milestone overview and every completed task implementation summary in the milestone's declared task set.
- Child dependencies: follow-up planning may use reconciliation findings, but reconciliation itself does not create new tasks unless a later explicit planning workflow is invoked.
- Downstream usage: reconciliation answers whether the combined task outcomes satisfied the milestone intent and acceptance criteria, records validation sufficiency, dedupes discovered or backlog work, and names any review concerns.
- Expected outputs: milestone-level `reconciliation.md` with `reconciliation_status: completed` and `status: completed` only when all criteria have been reviewed against task-summary evidence and no placeholder review content remains.
- Evidence handoff: reconciliation points to completed task summaries and validation or review evidence so downstream readers can inspect the supporting artifacts instead of relying on a status-only verdict.
- Metadata ownership: use the supported reconciliation update command for CLI-owned reconciliation status transitions; direct metadata edits require an explicit manual exception.

## Canonical Sources

- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/milestone.agent-lifecycle-guide.md`

## Source And Traceability Links

Use these sources to verify the planning-layer model without duplicating their full content here:

- Source specification: `.day-shift/specs/16-onboarding-experience-redesign/onboarding-experience-redesign.md`
- Spec registry metadata: `.day-shift/specs/index.json`
- Slice overview: `.day-shift/planning/16-onboarding-experience-redesign/overview.md`
- Phase overview: `.day-shift/planning/16-onboarding-experience-redesign/phases/02-reference-and-layer-relationship-docs/overview.md`
- Milestone overview: `.day-shift/planning/16-onboarding-experience-redesign/phases/02-reference-and-layer-relationship-docs/milestones/03-planning-layer-relationship-reference/overview.md`
- Phase 01 boundary evidence: `.day-shift/planning/16-onboarding-experience-redesign/phases/01-audience-and-responsibility-separation/milestones/03-prompt-template-reference-boundaries/prompt-template-reference-boundary-map.md`

## Template Shape Links

Templates define artifact shape. They do not decide when a workflow should create, update, review, or reconcile an artifact.

- Specification template: `.day-shift/templates/specification.md`
- Slice overview template: `.day-shift/templates/slice-overview.md`
- Phase overview template: `.day-shift/templates/phase-overview.md`
- Milestone overview template: `.day-shift/templates/milestone-overview.md`
- Task definition template: `.day-shift/templates/task-definition.md`
- Implementation summary template: `.day-shift/templates/implementation-summary.md`
- Milestone reconciliation template: `.day-shift/templates/milestone-reconciliation.md`

## Workflow And Prompt Links

Workflow docs own procedure. Prompt files own reusable handoff instructions. This reference owns the conceptual relationship map.

- Specification, slice, phase, milestone, and task planning procedure: `.day-shift/workflows/02-plan-from-spec.md`
- Task implementation procedure: `.day-shift/workflows/03-implement-from-task.md`
- Implementation-summary and milestone-reconciliation procedure: `.day-shift/workflows/04-summarize-and-reconcile.md`
- Task agent lifecycle: `.day-shift/workflows/task.agent-lifecycle-guide.md`
- Milestone agent lifecycle: `.day-shift/workflows/milestone.agent-lifecycle-guide.md`
- Milestone-to-task prompt: `.day-shift/prompts/user/milestone.next.md`
- Task-to-implementation prompt: `.day-shift/prompts/user/task.next.md`
- Implementation-to-reconciliation prompt: `.day-shift/prompts/user/implementation.next.md`

## Adjacent References

Related reference pages own adjacent detail that should not be repeated here:

- Command-family write and read-only boundaries: `.day-shift/references/commands.md`
- Spec registry fields and linked-slice metadata: `.day-shift/references/spec-registry.md`
- Metadata families, status fields, and parent-link mutation boundaries: `.day-shift/references/metadata.md`
- Prompt/template responsibilities and artifact-shape cleanup boundaries: `.day-shift/references/prompts-and-templates.md`
- Validation, review, implementation-summary gates, reconciliation gates, and structural-pressure policy: `.day-shift/references/validation-and-review.md`
