Write acceptance criteria

This page shows you how to add acceptance criteria to a requirement and how to phrase them so tests and PR verification can use them.

Prerequisites

• A requirement in a project you can write to. See Write a good requirement.

The model

An acceptance criterion (AC) is one statement that must be true for the requirement to be met. Spectrace stores a requirement's criteria as an ordered list on the requirement itself; there is no separate table.

Each criterion has:

The completed flag drives the progress bar on the requirement page and the workflow gate described below. It says nothing about whether a pull request satisfied the criterion; that is a separate verdict recorded per verification run.

Add, edit, and complete criteria

On the requirement page, the Acceptance criteria card lists the criteria with a <done> / <total> done count.

1. Add a criterion

   Click Add criterion, type the text, and press Add (or Cmd/Ctrl + Enter). The placeholder suggests the Given … When … Then … form, but any text is accepted.

2. Edit a criterion

   Click the criterion text to open it for editing, change it, and press Save. Escape cancels.

3. Mark it complete

   Click the checkbox at the left of the criterion. It fills green with a tick and the text is struck through. Click again to mark it not done.

4. Remove a criterion

   Hover the row and click the × at the right.

Every one of these actions saves the whole list back to the requirement and writes a revision entry, so the Versions card shows criteria added, edited, and removed. If the requirement is linked to a Jira issue, Spectrace also regenerates the checklist in the Jira description.

Other ways to toggle a criterion:

• VS Code extension — Spectrace: Mark Acceptance Criterion Complete (Cmd/Ctrl + Shift + C) on the active requirement. See VS Code extension.
• MCP — spectrace_acceptance_criteria_toggle flips or sets one criterion; spectrace_acceptance_criteria_set replaces, appends to, or edits the list. See Tool reference.
• REST — PATCH /api/v1/requirements/:id/acceptance-criteria/:acId with { "completed": true }.

Where AI generates criteria

Spectrace drafts criteria in three places, and every AI-written criterion carries a category and, where relevant, complianceRefs:

1. Import wizard. Every extracted requirement arrives with criteria. In the Review step you can edit them, untick ones you do not want, and click Suggest more with AI to ask for additional criteria for one requirement. See Import requirements.
2. Quick add. On the project board or list, open Add requirement → Quick add (or the + on a board column). The dialog has a Generate in background section; tick Acceptance criteria and Spectrace generates them from your title and description after the requirement is created. The requirement page shows per-artefact progress until they land.
3. Issue sync. Requirements created from Linear, Jira, or GitHub issues by webhook are enriched the same way when the project has auto-enrich on. If the compliance check flags a gap, the requirement's enrichment status becomes needs_clarification.

Generated criteria are drafts. Read them, delete the ones that describe your implementation rather than the behaviour, and add the ones the model missed. There is no "generate criteria" button on the requirement page itself.

Why the verifier depends on them

Test generation and PR verification both start from the criteria list:

• Tests. The Generate button on the tests card produces one Gherkin test pack from the criteria; with no criteria it is disabled with "Add acceptance criteria first". Test generation also runs automatically when a requirement is created with criteria in the web app (the import wizard is the exception — it queues no tests), when the first criterion is added to a requirement that had none, and when it moves to In Dev with no tests yet.
• PR verification. Each criterion is graded on its own against the diff as satisfied, partial, not_found, contradicted, or unclear, with file-and-line evidence for anything found. The GitHub check run title reads <met> of <total> criteria met, and a single contradicted criterion turns the check red. See Read a verification result.

A vague criterion therefore does not fail quietly. It shows up as unclear or not_found on every pull request, and the reviewer has to decide what it meant.

What makes a criterion verifiable

• One behaviour per criterion. "Rejects an expired link and shows the resend form" is two checks; a diff can satisfy one and not the other.
• Observable from code or tests. State the input and the visible outcome: status code, error copy, redirect, stored value, emitted event.
• Concrete thresholds. "Under 300 ms at p95", "at most 5 attempts per hour", "expires after 15 minutes".
• No process statements. "Product signs off on the copy" cannot be found in a diff and always lands as unclear.
• Name the negative cases. The verifier's contradicted verdict needs a criterion that says what must not happen ("does not reset the lockout counter on a failed attempt").

Workflow gate

Moving a requirement to In Review or Done in the web app fails with N acceptance criteria not completed while any criterion is unchecked. A requirement with an empty list passes the gate, because there is nothing to check. See Workflow stages and approvals.

What done looks like

The requirement page shows a criteria list where each line names one observable behaviour, the count reads 0 / N done before work starts, and the tests card offers Generate. If instead the tests card says "Add acceptance criteria first", the list is empty; if a pull request comment lists most criteria as unclear, the criteria describe intent rather than behaviour and need rewriting.

Related

• Write a good requirement
• How PR verification works
• Read a verification result
• Verify before you push