Turn intent into testable behavior
Describe what the user and system must do, including constraints, failures, and evidence of success.
Why this matters
Say you promised "easy project renaming" and your agent built it — but viewers can rename too, and a typo wipes the draft. Requirements stop that. They connect your promise to behavior someone can verify: specific enough to reject a wrong-but-plausible build, small enough to revise when you learn.
What to understand
"Show a table" names a solution. "An approver can compare pending requests by urgency and act on one" names something you can actually test. Keep the table when it's a real constraint — just say so, separately from the need.
For each important action, write down who does it, what starts it, what's allowed, what changes, and what the person sees. Ask your agent: "for this action, who can do it, what starts it, and what does the person see after?"
Watch for
- Vague quality words — "fast," "easy," "reliable" — with no condition you could check.
- Numbers copied from someone else's example, never accepted for this product.
- Unknowns written up as if they were already built — especially the agreed exchange with the server.
- A screenshot treated as proof that a save worked or permissions held.
- Rejected input erasing the draft; repeated submission creating duplicates.
Strong default
Name the condition alongside every target. Split unknowns from requirements — say who must settle the open contract. Give shared behaviors short stable IDs so notes, designs, and tests point at the same thing, and match the paper trail to the risk.
When this doesn't apply
A suggested budget only becomes a requirement when your team accepts it for this product. A small feature may need only a short table; a regulated or multi-team project needs a stronger paper trail. Match the weight to the risk — don't carry the heavy process everywhere.
In practice
| Requirement | Acceptance example |
|---|---|
| Editors can rename projects they belong to. | An editor's valid rename is still there after reload. |
| Viewers cannot rename projects. | A viewer's rename is refused — what you're allowed to do, checked on the server — and nothing saved changes. |
| Rejected input does not erase the draft. | An overlong name shows a field error and keeps what you typed. |
| Repeated submission does not create duplicates. | Pressing twice has the same effect as once — safe retry, agreed up front. |
These are sketches — your product, who-can-do-what rules, and data shape decide the real ones.
Make quality measurable in context: name your target standard and the task and input checks you'll run for accessibility; the smallest screen and content stresses for responsiveness; the waiting-time metric, conditions, coverage, and whether the number is a guess or agreed for performance; what survives a dropped connection or crash for reliability; what data reaches the browser, logs, analytics, and saved drafts for privacy.
Surface dependencies early. Say "Export CSV" out loud and you'll feel the hidden work: how big is the data, who may export, does it run in the background, will Excel mangle the output? Write down the API abilities, who owns the data, who-may-do-what rules, service limits, and working assumptions that shape the experience.
Verify
After building, mark each behavior met, failed, changed, or unverified — with proof. A screenshot proves how it looks, not that it saved or that permissions held.
Related skills
Use $requirements to write or revisit these. Continue with information architecture for where the task lives, or full-stack understanding for what it depends on underneath.
Last updated on