Free editable template
Acceptance criteria template
“Build a contact form” leaves too much for the builder to decide. An acceptance brief names what the person using it should be able to do, how failure should behave and what the reviewer needs to see.
Markdown (.md). No signup. Free to use, edit and share, including at work.
How to use it
- Describe one change, who needs it and what is outside the task. Keep the scope small enough for someone to review.
- For each case, write the starting state, the action and an observable result. Replace words like “works well” with a behavior you can demonstrate.
- Include normal use, invalid input, relevant permissions and nearby behavior that must keep working.
- Save the agreed brief before work begins. If a criterion changes, record the reason and have it reviewed before accepting the new target.
Open the file in any text editor, fill in the brackets, and paste it into your pull request or issue tracker. No attribution required.
Worked example
Example: replace “validate the form” with observable behavior
- Starting state
- A visitor has entered a name and a message but left the email field empty.
- Action
- The visitor presses Send message.
- Expected result
- An email error appears. The name and message stay filled in. No message is sent.
- Evidence needed
- A test covering the empty email case and a recording from the delivered preview build.
The full template
# Acceptance brief Fill this in before work begins. Share it with the builder and reviewer. You do not need Ranex. ## The task Change: [one concrete change] Who needs it: [person or role] Problem it solves: [what they cannot do today] Out of scope: [what this task does not include] ## What a person should be able to do Starting point: [page, command or current state] Action: [what the person does] Expected result: [what they can observe] Example: From an empty contact form, submit without an email address. Show an email error, keep the message text and do not send the form. ## Acceptance cases | Case | Starting state and action | Expected result | Evidence needed | | --- | --- | --- | --- | | Normal use | [input and action] | [observable result] | [test output or recording] | | Invalid or missing input | [input and action] | [clear failure behavior] | [test output or recording] | | Permission boundary, if applicable | [role and action] | [allowed or denied result] | [test output] | | Existing behavior | [nearby workflow] | [what must still work] | [regression check] | ## Review agreement Acceptance criteria agreed by: [name] Saved before work begins at: [commit or dated document] Evidence must identify: [the exact commit or build under review] Reviewer: [person responsible for acceptance] If a check cannot run: [record it as unverified and assign a next step] If the criteria change: [record why and obtain review before treating the new criteria as accepted] ## Handoff Version delivered: [commit or build] Evidence: [links] Known gaps: [list] Review decision: [ready / changes needed / unverified] --- From Ranex: https://ranex.dev/resources Free to use, edit and share, including in commercial projects. No attribution required.
Common questions
How detailed should acceptance criteria be?
Detailed enough that the builder and reviewer can observe the same outcome. State the behavior and relevant constraints; leave implementation choices open unless they are part of the requirement.
Can the AI help write the brief?
Yes. Use its draft to surface questions, then have the person who owns the requirement review it. The builder should not silently rewrite the acceptance criteria to fit the code it produced.
Keep the evidence with the work.
The template helps you describe and review the work. Ranex checks signed evidence against a policy for an exact version of the code.