Spec

A spec is the contract the adversary loop reviews against. Without one, "correct" collapses into "what the generating agent happened to assume". Keep it under two pages — a spec nobody reads is decoration.

Structure

# <feature name>
YYYY-MM-DD · status: draft | building | shipped

## Problem
One paragraph. What hurts, for whom, and why now.

## Behavior
The user-visible contract, written as observable statements:
- "A scheduled post more than 2h late fails with <message>; it never
  publishes silently at the wrong time."
Each line here is a future review checklist item — write them checkable.

## Data
Schema deltas only: new columns/statuses/tables, with types and the reason
each exists. Note every claim on shared resources (migration slot, enum
value, queue name) — these feed /decompose's collision check.

## Processes
New or changed jobs, crons, handlers. For each: trigger, what it reuses
from existing paths (name the module), idempotency/race story.

## Failure policy
For each external call and each race: retry / fail loudly / degrade.
What the user is told, in which surface.

## Non-goals
Explicitly out. This section prevents scope creep during generation more
than any other.

## Open questions
Each with an owner and a default-if-unanswered.

Rules

• Prefer reuse statements ("flips to PENDING and enqueues the same job pair as the ad-hoc path") over parallel-system designs. The reviewer should be able to verify reuse by reading the named module.
• If a spike exists, its production note seeds Data/Processes verbatim.
• Architectural decisions made here (new dependency, new pattern, new boundary) each get an ADR in docs/adr/ — one paragraph of context, decision, consequences.
• Save to docs/specs/YYYY-MM-DD-<name>.md, commit it with the feature.

Exit

The spec file, plus updated CONTEXT.md entries for any new domain terms (state names, job names, user-facing nouns) so every later session uses the same words.