prd-contract

# The PRD contract — specs/requirements/prd.md The PRD speaks **product language**: what the system does and for whom, never how it is built. Engineering altitude begins at `specs/design/`. ## Sections, in order ```markdown # <project name> — PRD ## Problem Statement <who hurts, how, and what today's workaround costs — a short paragraph> ## Solution <what this product is, in one paragraph a stakeholder can repeat> ## Actors <one bullet per actor: name + what they can broadly see/do, product-level. Every actor cited by a story is defined here first.> ## User Stories <a single numbered list, the spine of the document:> 1. As a <actor>, I want <feature>, so that <benefit>. 2. … ## Product Decisions <policy choices at product altitude: sign-in approach, notification channels, which external services the product depends on. An external service is named by capability ("transactional email"); a concrete provider appears here ONLY as a given the business already holds — a Registered External resource of the org (an org default, written without asking) or a service the user said they already use or must use ("Payments: Stripe — finance has the account"). With no such given the line stays capability-only; the agent never proposes a provider here, and a provider line is never tagged `*assumed*` — choosing a service is the user's, on the dependency's definition at design. Decisions taken from an org default are ordinary entries; a decision the agent made itself, because the user has not answered it yet, ends with the literal tag `*assumed*` — that exact emphasised word, no parentheses or brackets around it. The console reads the tag to count what is unsettled and to draw the Settle control on the line, so a decorated variant costs the user the ability to challenge the judgment. The tag lives exactly as long as the user has not answered: the moment they do — even by confirming what was assumed — the tag comes off and the line stays as a settled decision.> ## Out of Scope <what this project deliberately does not do> ## Open Questions <numbered; each is a fact only the user holds — marked, never guessed. It is resolved when its answer moves to the section it belongs in and the entry leaves this list. An entry the user has declined for now is marked "deferred — the user will decide later", which tells you to stop raising it. Open questions gate nothing: the document is readable, designable and buildable with them outstanding.> ## Further Notes <anything real that fits nowhere above; omit the section when empty> ``` ## Rules - **Story numbers are permanent.** New stories append with fresh numbers; numbers are never reused or renumbered — designs, criteria, and tasks cite them. - **Every statement lands.** Everything the user said in the brief or the interview appears somewhere above — as a story, a decision, an out-of-scope line, or an open question. A user statement with no home is a defect. - **Actors before citation.** A story only names actors the Actors section defines. - **The story list is total.** Every story the PRD defines ships. Work that should come later is an Out of Scope line, or it is not a story yet. - **No acceptance criteria.** They live in `specs/validation/acceptance/<slug>.feature` — the acceptance oracle. The PRD never duplicates them. - **The PRD body stays lean.** A story is one line; what the product does is the story list, not an elaboration of it. There is no separate per-feature document — the PRD is the whole requirements document.