How to write acceptance criteria a gate can check
Given/When/Then criteria are what turns “the model says it is done” into something a test can disagree with. This is how to write them so the gates and the test agent can use them.
Acceptance criteria are the first gate in Turnado: an item cannot leave New without them. That is not bureaucracy. Everything downstream — the test cases the test agent derives, the Definition of Done, the human test — reads these sentences. Vague criteria do not fail loudly; they produce work that passes and does the wrong thing.
The form
Turnado uses Given/When/Then, and it renders the three words distinctly so a criterion is scannable at a glance. Each criterion is one behaviour: a starting state, a trigger, an observable result.
Given a registered customer, when the correct password, then dashboard within 2 s
Given 5 failed attempts, when the 6th attempt, then blocked for 15 min + email
Five rules that make the difference
- Make the result observable. “Then the user is happy” cannot be tested. “Then the dashboard is shown within 2 s” can.
- One behaviour per criterion. If you need the word “and” twice in the Then, you have two criteria.
- Put the numbers in. Five attempts, fifteen minutes, two seconds. A number is the difference between a test case and an opinion.
- Write the unhappy path. The error, the timeout, the empty state. Most production bugs live in the criteria nobody wrote.
- Name the state you start from. “Given a registered customer” and “Given a customer with an expired session” lead to different code.
What Turnado does with them
| Where | What happens |
|---|---|
| The first gate | An item with no criteria cannot move from New to Refined. The condition is acceptance_criteria_present and it is a plain function, not a judgement. |
| The dev agent | The criteria are part of the context package it receives — they are the specification it works against, not a hint. |
| The test agent | Test cases are derived from the criteria. Weak criteria therefore mean weak tests, quietly. |
| The human test | The tester reads the same sentences. If the criteria say nothing about the error case, nobody tests the error case. |
The Definition of Done is a separate thing
Acceptance criteria say what the software must do. The Definition of Done says what must be true before you call it finished — unit tests above a threshold, review approved, deployed to TEST, human test passed. They are separate blocks on the ticket because they are separate conversations: the first is with the customer, the second is with your own team.
How many criteria should a user story have?
Enough to describe the behaviour and its exceptions — in practice two to five. A story that needs ten is usually two stories, and one that needs none is usually a task rather than a story.
Can an agent write its own acceptance criteria and then approve them?
It can propose them. It cannot approve its own work: whoever writes code does not approve it, and the permissions that would let an agent force a status past a gate are on a list no agent ever gets, whatever roles you give it.
What if the criteria change halfway?
Change them on the ticket. The change is recorded with who made it and when, and the gates recalculate from the new state — there is no cached “was approved once”.