acceptance-criteria-gwt

Acceptance Criteria (Given/When/Then)

Overview

Acceptance criteria are the contract QA tests the product against and the PM verifies at UAT. If a criterion isn't executable, it can't be verified — and unverifiable criteria are where defects hide.

Core principle: Every criterion is an observable behavior QA can execute with a command or a click path. No aspirational adjectives.

The shape

Given [precondition], When [action], Then [measurable result].

Where they go

Criteria live in the board task's own acceptance_criteria field — an array of strings, one criterion per item, passed to create_board_task (or update_board_task to replace the whole list). Each item becomes a checkbox the implementer ticks with set_criterion_completed, and that QA (in ready_for_qa/in_qa) and you (in pm_uat) then rule on independently with review_criterion. The tick is the implementer's claim — QA and PM never call set_criterion_completed; your verdict is review_criterion.

Never write them into description. A criteria block pasted as markdown leaves the task's checklist empty: nothing to tick, nothing the move guard can check, and the prose copy goes stale the moment the real criteria are edited.

Testability gate

For each criterion, before you save it, write down:

• who executes it — QA in in_qa, and the PM in pm_uat with browser or mobile tools (or http_request against the task's own preview when the surface is an API, not a screen);
• the action — a click path, a URL, or a request;
• the exact observable — text, a count, an element state, or a file.

If the behaviour is user-facing, the Then must be visible in the UI — not a status code standing in for what the user sees. If nobody outside the code can observe it, it belongs in technical_description, not in a criterion.

Declarative When, concrete Then

Write the When as what happens, not the click-by-click path — the cucumber test: "Will this wording need to change if the implementation changes?" If yes, it's too imperative. One behaviour per criterion. Put exact copy strings in quotes in the Then; "an error appears" is not testable, "'Title must be at most 200 characters' appears under the field" is.