Core Concepts · 5.3

Acceptance criteria

What a criterion holds, how its priority and verification method work, how results are reported, and the gate that keeps a story from being marked dev complete too early.

Acceptance criteria turn "I think it's done" into something you can check. Each criterion is one statement of what must be true when the story is built. Agents build against them and report on each one, and a person approves the story once they've read the results.

What a criterion holds

Field	What it is
Text	The plain statement, for example Double-booking the same slot is impossible.
Given / when / then	Optional. The same statement split into a starting state, an action and an outcome.
Priority	`must`, `should` or `could`. Without one, a criterion counts as `should`.
Verification method	How it gets checked (below).
Last result	The most recent report: `pass`, `fail` or `blocked`, the evidence, any caveat, which attempt it was, who reported it and when.

This priority is a separate scale from a story's priority, and only one question matters: is it a must? A could criterion behaves exactly like a should.

On a story's Spec tab, criteria are numbered cards (01, 02…), and + Add puts another on the list. Each card says how many tests prove it, or No test in amber.

Write outcomes, not solutions

A criterion says what has to be true, not how to build it. That leaves your agent free to choose how. IntentDocs flags a criterion that names an implementation detail, such as a component, file or library, so you can reword it, choose Move to Implementation to take the detail out of the criterion, or choose Keep. A dashed card is one that hasn't been checked for this yet.

Verification methods

Method	How it's checked
`executable`	A shell command with an expected result. `npx intentdocs check` runs it and gets a real pass or fail.
`agent_self_check`	A question for the agent to answer about its own work.
`visual_render`	Someone looks at the rendered screen: an agent that can see, or a person.
`founder_confirm`	A person confirms it directly. An agent can't close it on its own.

npx intentdocs check runs only executable criteria. It lists the others as manual.

Reporting results

Agents report with the MCP tool report_criteria:

{
  "story_id": "PB-42",
  "results": [
    {
      "criterion_id": "…",
      "status": "pass",
      "detail": "Ran npm test -- booking.spec.ts: 12 of 12 passed",
      "caveat": "Only tested with the default time zone"
    }
  ]
}

detail is the evidence. "Ran the booking tests, 12 of 12 passed" is useful. "Done" is not.
caveat is what a person should read before accepting the result. A story with a caveat on any result is never approved in bulk.
IntentDocs counts attempts itself: each report on a criterion is its next attempt.

From the terminal, npx intentdocs check --report runs the executable criteria and posts the results as reported by a person.

Tests prove criteria too. When an agent saves a test with save_tests, it links the test to the criteria it proves. With CI reporting on, your test suite reports each test's result itself. See Verification.

The must gate

A story can't be marked dev complete while any must criterion's last result isn't pass. That includes criteria that are failing, blocked or have never been reported. should and could criteria never block.

MCP: complete_story returns the blocking criteria instead of completing the story, unless the agent passes force: true.
CLI: npx intentdocs done lists the blocking criteria and asks Mark done anyway?. The override is recorded.

The gate makes "dev complete" mean what it says. Skipping a must is always visible.

When a criterion keeps failing

If a must criterion keeps failing, the agent should stop and ask rather than guess. raise_blocker records what it was trying to do, what's failing, how many attempts it made, and the one decision it needs from you. The story turns red and reads blocked until you resolve it. The prompts IntentDocs gives agents say to do this after three failed attempts.

Changing criteria

Tool	Use it to
`add_criteria`	Add criteria to a story.
`update_criterion`	Reword one criterion or change its priority. Its id and results stay.
`preview_criteria_replacement`	See what replacing the whole set would remove, including results it would lose. Writes nothing.
`replace_criteria`	Replace every criterion on a story.

You can also cancel a single criterion in the web app. A cancelled criterion stays on the record but no longer counts.