---
prompt_version: 1
layer: task
action: build
---

# Prompt: Build Task Definition

Use the upstream milestone, phase, slice, source spec, and repository context to create or update a task definition.

## 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 exactly one implementation-sized task: one coherent repository change that a standard implementation agent can complete, validate, and roll back independently.
- The task must have one primary outcome and a bounded set of implementation target paths.
- Supporting edits are allowed only when they are directly required to complete and validate that one primary outcome.
- Treat the task as too large and split it when it includes multiple independent outcomes, unrelated target-path groups, separate validation strategies, separate rollback paths, mixed readiness states, or more than one unresolved implementation decision.
- Treat the task as too small and merge it into the nearest related task when it is only a trivial mechanical edit with no meaningful behavioral, contract, validation, or artifact impact, unless sequencing or rollback isolation requires it to stand alone.
- Use the minimum task body needed for safe implementation. Do not add prose that only expands inferred context without changing scope, evidence, validation, or rollback clarity.
- Prefer `implement-*` tasks for executable repository changes; use `document-*` only when implementation would be unsafe without first authoring or finalizing a missing written contract, unresolved boundary, required shared decision, or evidence record.
- Use `define` in task titles, slugs, objectives, or acceptance criteria 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 task changes code or runtime 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 the task.
- Do not preserve or introduce repeated `document-*` lanes by default. If a surrounding milestone already has a downstream implementation lane for the same outcome, allow at most one supporting `document-*` task unless repository evidence shows multiple independent blockers with different target-path, validation, or rollback boundaries.
- Include enough evidence for an engineer or agent to implement safely.
- Preserve existing user-authored content when updating an existing task definition.
- When revising an existing task definition, always refresh readiness, status, dependencies, and lifecycle/closure metadata so it reflects the current task state rather than the original draft state.
- Order sibling tasks by dependency, not just by topic grouping: if one task creates or renames a producer artifact and another task repoints consumers to it, place the producer task first.
- Do not mark a task `ready to implement` when it depends on a later-numbered sibling task or on an output that does not exist yet; either reorder the tasks or mark the task `blocked` with the missing dependency named explicitly.
- Set readiness honestly: `ready to implement`, `needs more evidence`, or `blocked`.
- After creating or revising the task definition, run the Day Shift CLI readiness check before finalizing the response:

```sh
<day-shift-cli> task readiness-review --task-definition [Relative Path To Task Definition]
```

- Include the CLI result in the build output and reconcile any mismatch between CLI findings and the task definition updates made in this pass.
- After creating or revising the task definition, run `<day-shift-cli> validation links-check --scope planning --artifact <task-definition-path>` as read-only local trace-link evidence, then run `<day-shift-cli> link materialize --dry-run --artifact <task-definition-path>` and use `<day-shift-cli> link materialize --write --artifact <task-definition-path>` only when the dry-run reports safe selected-artifact body-reference changes. Treat validation findings as evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as permission to mutate metadata, update summaries, or create reconciliation.
- Keep section roles distinct: `Upstream Context` is for reference-only planning/spec evidence, `Implementation Target Paths` is only for files or directories expected to be created or modified by the task, and `Dependencies` is for required read-only inputs, prerequisite artifacts, or supporting code that may be consulted without being a target change.
- Put only concrete repository-relative paths in `Dependencies`. Avoid prose wrappers such as "Existing behavior in `path`" because readiness review treats dependency bullets as artifact references.
- Put dependency explanation, contract context, and behavioral notes in `Upstream Context`, `Risks`, or `Assumptions`.
- Do not repeat upstream reference artifacts under `Implementation Target Paths` unless the task is actually expected to create or modify those artifacts.
- Use `ready to implement` only when objective, upstream references, implementation target paths, current behavior, desired behavior, acceptance criteria, validation commands, rollback or recovery notes, risks, dependencies, constraints, lifecycle/closure expectations, and open questions are all sufficiently handled.
- Before finalizing the task, verify that its single primary outcome, target paths, validation commands or inspection steps, and rollback or recovery notes still describe one coherent change; if they do not, split the task or mark it not ready.
- Do not silently absorb newly discovered work into the current task; record it as follow-up planning, discovered work, or backlog work instead.
- Stop and report instead of guessing when the selected artifact and upstream evidence conflict materially.
- Keep implementation results out of this artifact.
- 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` and `Assumptions` none-state, and no leaked scaffolding prose or unresolved placeholders in the saved artifact.
- When the parent slice has `planning_depth: lightweight`, use the direct slice-level lightweight task shape: set `planning_depth: lightweight`, link `upstream.slice_overview` directly to the slice overview, omit `phase`, `milestone`, `upstream.phase_overview`, and `upstream.milestone_overview`, and keep the paired implementation summary in the same `.day-shift/planning/<slice-dir>/tasks/<task-slug>/` directory.

## Template Reference

Use `.day-shift/templates/task-definition.md` as the standard milestone-parented artifact shape.

For lightweight slice-parented tasks, use `.day-shift/templates/lightweight-task-definition.md` for `task-definition.md` and `.day-shift/templates/lightweight-implementation-summary.md` for the paired `implementation-summary.md`.

Populate the lifecycle/closure expectations so the resulting task definition clearly states how completion will be recorded after implementation.

## Required Output

Create or update a task definition artifact with the configured template sections and valid front matter.
