Write requirements and acceptance criteria

Why this matters

Yesterday you wrote down who the app is for and the one loop it serves. That page is still a wish. Today you turn it into behaviour you can check — statements so specific that you, a stranger, or an AI agent can look at the running app and agree on whether each one passed. Ambiguity is the enemy here: every vague requirement becomes a decision someone makes silently at 11pm, and silent decisions are the ones that surprise you in the demo.

By the end of the hour you have a specification another developer could implement without guessing.

User stories: one behaviour each

A user story is one sentence describing one thing one user wants, in a fixed shape:

As a <user>, I want <to do this>, so that <this outcome>.

The shape is not decoration. The so that clause is a test: if you cannot finish it without repeating the middle clause, the story has no purpose behind it and probably should not be built.

As Maya, I want to record a completed calibration for an instrument,
so that its calibration history is accurate without a spreadsheet.

One story, one behaviour. "I want to record and edit and delete calibrations" is three stories. Split them, because each will be built, tested, and demonstrated separately — and because a story you can only half-finish leaves the app half-broken.

Five to eight stories is the right size for a capstone. Fewer and you have not thought it through; more and you are writing next year's roadmap instead of this fortnight's project.

Acceptance criteria: the checkable part

An acceptance criterion is a specific observable behaviour with its conditions and its expected result. It is the strongest form a requirement can take, and it is what makes a story finishable — without it, "record a calibration" is done whenever you feel like saying so.

Write each one in three lines:

Given <the starting state>
When  <the user does exactly this>
Then  <this observable thing is true>

Compare. These are not requirements at all:

Make the form fast.
The app should be modern and intuitive.
Handle errors properly.
Use best practices.

None can be checked. "Fast" by whose stopwatch, "modern" by whose taste, "properly" meaning what? Each is a decision you have postponed while feeling like you made one. Now the same intentions, written as acceptance criteria:

Given an instrument exists with no calibrations
When  Maya submits the form with date 2026-03-01 and technician "Maya R"
Then  that calibration appears at the top of the instrument's history list
      and the page shows "Calibration recorded"

Given the calibration form
When  Maya submits it with the date field empty
Then  the app does not save anything
      and the message "Date is required" appears next to the date field

Edge cases and failure cases

Your criteria so far describe the day going well. Most defects live in the other cases, and beginners skip them because they are boring — which is exactly why they survive to the demo.

Run every story through this list and write a criterion for any row that applies:

Case	Ask
Empty	What if the field is blank, or the list has no rows yet?
Too long	What if the note is 5,000 characters?
Wrong type	What if the date is banana, or the quantity is -4?
Missing target	What if the instrument ID does not exist?
Duplicate	What if the same record is submitted twice?
Not allowed	What if this user should not be able to do it at all?
Offline	What if the server is unreachable when Submit is pressed?

For each one, the criterion must say what the user sees, not only what the code does. "Returns 400" is half an answer; the other half is the message on the screen.

Data sensitivity

Before you design tables tomorrow, decide what each piece of data is. Go through every field your stories imply and label it:

• Public — fine for anyone to see. Instrument model, calibration interval.
• Internal — fine for your user, not for the world. Which instrument is overdue.
• Personal — identifies a human. Technician name, email. Storing it means you are responsible for it.
• Secret — must never appear in the database as plain text, in logs, or in a Git repository. Passwords (hashed only, from Day 51), API keys, tokens.

Then write two lines in your spec that you will check against later:

NEVER LOGGED: technician email, session tokens
NEVER RETURNED BY THE API: password hashes, internal notes field

Walkthrough: one story, fully specified

Take the thin slice from Day 78 and write it out properly. Create docs/spec.md:

STORY 1
As Maya, I want to record a completed calibration for an instrument,
so that its calibration history is accurate without a spreadsheet.

ACCEPTANCE CRITERIA
1. Given an instrument exists
   When Maya submits date 2026-03-01 and technician "Maya R"
   Then the record appears at the top of that instrument's history
        and the list count increases by one

2. Given the form
   When Maya submits with the date empty
   Then nothing is saved
        and "Date is required" appears next to the date field

3. Given the form
   When Maya submits a date in the future
   Then nothing is saved
        and "Date cannot be in the future" appears next to the date field

4. Given an instrument ID that does not exist
   When a calibration is submitted for it
   Then the API responds 404 and no row is written

DATA
- calibration date: internal, required, not in the future
- technician name: personal, required, max 80 characters
- notes: internal, optional, max 500 characters

DONE WHEN
All four criteria pass on a freshly seeded database, checked by hand.

Notice what happened: criterion 3 did not exist until the edge-case table was applied, and it is a real product decision — you just made it deliberately instead of discovering it in a bug report.

Your turn

Write docs/spec.md for your own project.

1. Write 5–8 user stories in the As a … I want … so that … shape. Mark exactly one as SLICE 1 — the thin slice from yesterday. That is what you build on Day 82.
2. For each story, write 2–4 acceptance criteria in Given / When / Then form.
3. Run the edge-case table over every story. Add a criterion for each row that applies. Expect this to roughly double your criteria count; that is the point.
4. Ban the vague words. Search your file for fast, modern, intuitive, properly, clean, robust, seamless, user-friendly. Replace each with something observable, or delete the line.
5. Copy your non-goals from yesterday into the spec so it is one document.
6. Add the data sensitivity block: label every field, then the NEVER LOGGED and NEVER RETURNED BY THE API lines.
7. Add a DONE WHEN section: the exact conditions under which the whole project is finished.
8. Run the reviewer prompt above, apply the findings you agree with, and commit: docs: acceptance criteria for capstone.

Common pitfalls

• Writing criteria that describe the implementation. "Then the calibrations table gets a row" is a design decision, not a behaviour. Say what the user can observe; you may still change the design tomorrow.
• One giant story. If a story needs more than four criteria, it is two stories. Split it before it becomes a week you cannot finish.
• Skipping the failure cases because "it obviously errors". Obvious to you today is invisible to you on Day 86. Write the message text now.
• Treating the spec as unchangeable. It is a living document. Changing it deliberately, with the date noted, is engineering. Drifting away from it silently is not.

Verify it yourself

Open today's reference, OpenAI's Codex CLI documentation, and read the guidance on writing prompts and giving the agent context.

1. Find what it recommends including so the agent knows when a task is complete. Compare that to your DONE WHEN section — is yours as specific?
2. Look for anything about verifying the agent's output. Which of your acceptance criteria could be checked automatically, and which need your eyes? Mark each criterion auto or manual.

Add both notes to the end of spec.md. On Day 82 an agent will implement SLICE 1 from these criteria, and the ones marked manual are exactly the ones you must check yourself.