requirements

Requirements

Write requirements about outcomes and observable behavior. Keep explicit user choices; do not replace their product with a preferred solution.

Work

Extract the user goal, initiating event, allowed actor, inputs, result, and failure behavior from the brief or running product.
Give requirements stable IDs only when traceability helps. Prefer “An editor can rename a project; a viewer cannot” to legalistic filler.
For each write, identify server authorization, validation, persistence, duplicate submission behavior, and what happens if the result is unknown after a timeout.
Specify applicable quality constraints with conditions: target devices, input methods, content size, latency measurement, supported languages, privacy, and availability. Mark proposed targets as proposals.
Name dependencies, unresolved contract questions, and excluded scope. Do not invent APIs or imply they exist.
When revisiting implementation, report which requirements are met, changed, missing, or unverified, with evidence.

Deliver

Use requirement → acceptance example → dependency/unknown. Add only enough examples to distinguish correct behavior from a plausible implementation.

Write each requirement as:

FR-01: [actor + behavior]. Accept: [observable example]. Depends/unknown: [...] NFR-01: [constraint + condition]. Verify: [scoped check] Close with out-of-scope, assumptions, open questions, and next step.

Include a failure or boundary case for consequential behavior. “Accessible,” “fast,” and “secure” need scoped verification criteria. Use $flow when branch order is the open question; $component when a reusable interaction needs a contract.

Worked example

FR-01: An editor can rename a project; a viewer cannot. Accept: a viewer's direct rename request is rejected by the server and the stored name is unchanged. Depends: role data per organization. FR-02: A rename that times out does not apply twice. Accept: resubmitting after a timeout leaves one stored name and one audit entry. Unknown: whether the API supports idempotency keys. FR-03: The project list keeps its status filter in the URL. Accept: a copied link opens the same filtered list. Depends: none. NFR-01: Renaming works with a keyboard alone. Verify: complete a rename without a pointer; focus returns to the project name. NFR-02 (proposed, not agreed): The project list shows usable content within 2 s on the client's field phones over a throttled mobile profile. Verify: measure on that device profile once the client confirms the target. Out of scope: bulk rename, rename history view. Assumptions: project names are unique per organization. Open questions: what a viewer sees when an editor renames a project they have open. Next: $flow for the rename path, including two editors renaming at once.

Gotchas

A permission check that only says the button is hidden passes a build that lets anyone call the API; include a direct-request case.
Writes fail a third way: the request times out after the server saved, so consequential writes need a retry requirement.
A requirement that names a component ("add a dropdown") locks in a solution before anyone designed it.
"Fast", "secure", and "accessible" cannot fail a test until they have a condition and a check.
Endpoint names written into requirements get treated as existing contracts; list undocumented APIs as unknowns.

Boundaries

Do not use when the idea is still vague (who it is for, what outcome it serves); use $intent instead.
Do not use when the open question is navigation or which pages exist; use $sitemap instead.
Do not use to map the step-by-step path of a task; use $flow instead.