Agent prompting tips and verb discipline

Day Shift works best when the first verb in a request names the outcome you actually want. This is especially important with define: natural-language inference can reasonably read “define caching” as implement caching, write documentation about caching, or set a contract for caching. Those are different deliverables, with different evidence and write boundaries.

define is not forbidden. It is a contract-setting verb: use it only when the requested output creates or revises a named durable boundary, schema, vocabulary, policy, rule, interface, or decision that later work will consume. Name both the contract and its downstream consumer so the intent is testable.

Choose the verb that owns the deliverable

If the outcome is…	Prefer	Example
Changed code, runtime behavior, or an executable workflow	implement	“Implement cache invalidation in the worker and validate the retry path.”
A new or revised contract consumed by later work	define	“Define the cache-consistency policy used by the API and worker.”
Explanatory prose about an existing behavior or decision	document	“Document the existing cache-invalidation policy for operators.”
Facts, observations, decisions, or completion evidence	record or capture	“Record the benchmark result and the affected paths.”
An initial artifact, directory, or workspace shape	initialize or scaffold	“Initialize the service fixture with the standard configuration.”
A readiness or gap assessment	review	“Review the task for cache-invalidation readiness.”
Test or inspection evidence	validate or verify	“Validate cache invalidation after a worker restart.”
A change to an existing artifact	update or revise	“Update the cache policy to include replay behavior.”
Implementation evidence rolled up to a checkpoint	reconcile	“Reconcile completed task evidence into the milestone.”
Decomposition into the next planning layer	plan	“Plan the cache reliability slice from the registered specification.”

Do not use mixed ownership such as “implement or define caching.” Decide whether the next output is executable behavior or a contract. If both are needed, state the order explicitly or split them: first define the named policy if implementation truly depends on it, then implement the code that follows it. When a written explanation is all that is needed, use document, not define.

Prompt agents with an observable outcome

Start requests with one precise verb, then name the output, scope, and evidence. This leaves less room for an agent to substitute planning prose for code or code changes for documentation.

Ambiguous request	Directed request
“Define caching.”	“Implement cache invalidation in src/cache/ and add an executable restart test.”
“Define the authentication docs.”	“Document the existing authentication boundary in the operator guide; do not change runtime code.”
“Define retries.”	“Define the retry-policy schema and its error-class vocabulary for the API and worker to consume.”
“Define and implement the migration.”	“Define the migration compatibility policy, then implement the selected migration command and validate it.”

Before authorizing work, ask for one primary outcome and the smallest target surface that can deliver it. Include the intended validation when behavior changes. If an agent presents a task title that uses define without a named durable contract, ask it to rename the task with the verb from the table before it creates or changes planning artifacts.

What a standard fresh install reinforces

Run day-shift init --dry-run first and inspect the planned files. A normal day-shift init seeds the standard agent entrypoint, policy packs, user prompts, references, workflows, and templates while preserving divergent workspace-owned files by default. Do not use --without-templates when you want the shipped prompting and workflow guidance: that option intentionally skips the shared authoring assets. If it was used, preview a normal init again and apply it only after checking the planned additions.

After initialization, start an automation session with the compact repository orientation:

day-shift agent --format json --detail compact

The installed .day-shift/agents.md tells agents to default to implementation-oriented tasks for executable work and to use a documentation-only define-* task only when a missing contract or unresolved boundary would otherwise block safe implementation. day-shift agent remind is the correction-focused reminder entrypoint; use it when an agent has drifted from that workflow.

The shipped prompt and review layers reinforce the same behavior:

• Build prompts reserve define for a durable downstream contract, and direct executable changes toward implement-*.
• Planning handoff prompts run a pre-save authoring audit that checks that distinction before saving generated artifacts.
• Specification, slice, phase, milestone, task, implementation, and reconciliation reviews warn when define does not name a contract, boundary, schema, vocabulary, policy, rule, interface, or decision.
• Task prompts prefer one implementation-sized outcome, bounded target paths, explicit validation, and an honest readiness state. Review results are evidence; they do not silently authorize extra writes.
• Prompts, workflows, and templates remain workspace-owned starting points. Inspect their current content and use the explicit prompt update or reconciliation workflow when you choose to customize or upgrade them.

These guardrails make the intended behavior visible and repeatable; they do not replace clear user direction. Agents can still receive ambiguous instructions, custom prompts can change the defaults, and warnings need a human or authorized agent to act on them. Keep using precise verbs, inspect the active repository guidance, and treat a review warning as a signal to correct the task language before it becomes implementation scope.

For the complete workflow rules, see Plan from a specification. For prompt ownership, resolution, and upgrade behavior, see Prompt and template catalogs and Upgrade prompt and template customizations.