Patterns / Specs

Acceptance criteria checklist

Turn "done" into a list of observable, yes-or-no checks the agent and you can both verify.

The problem

Agents tend to declare success as soon as the code looks plausible. Without an explicit definition of done, "it works" means whatever the agent last checked, which is often nothing.

The pattern

Write acceptance criteria as a checklist where every line is observable and binary: a command that passes, an output that matches, a behaviour you can trigger. Avoid adjectives like "clean", "fast" or "robust" unless you attach a measurable check.

Good criteria usually cover:

• The happy path (a concrete input and expected output).
• At least one edge or error case.
• Non-regression (existing tests or behaviour unchanged).
• Anything a human must eyeball, marked as such.

Ask the agent to report against each line explicitly when it finishes.

Template

## Acceptance criteria
Each item must be verified, not assumed. Report PASS/FAIL per line with evidence.

Functional
- [ ] Given <input>, <command or action> returns/produces <exact expected output>.
- [ ] Given <invalid input>, it fails with <error message or status code>, and no data is changed.

Non-regression
- [ ] `<test command>` exits 0.
- [ ] `<lint/typecheck command>` exits 0 with no new warnings.

Scope
- [ ] Only files under <paths> were modified.

Needs human check
- [ ] <UI or wording item a person should look at>

When not to use it

• Open-ended research or brainstorming where the output is ideas, not a verifiable artifact.
• When you cannot yet say what correct looks like. Use a spike to learn first, then write criteria.