Definition of done checklist
The short answer
A definition of done checklist has two layers: a short team-wide list that applies to every job, and Done When lines for the job in hand. Each line needs evidence, such as a test name, a staging URL or a link. A line with no evidence stays unchecked, so the job is not done.
A definition of done checklist is the list of things that must be true before any job counts as finished. The Done When lines are the ones specific to one job. Use both, and record the evidence for each. For the term, see What is a definition of done?.
TL;DR
- Two layers: Done When lines for this job, and a short team-wide checklist for every job.
- Each line must be checkable. If you cannot show it, it is a hope.
- Record the evidence per line: a test, a staging URL, a link.
- Merged is not done. Shipped is not verified.
- Keep the team list short enough that people read it.
When to use it: an agent or a teammate says "done" and you want to know what that means. When not: a change you will check by eye in a minute.
A definition of done checklist
The first part is the team-wide list. The second is the Done When lines for one job. The third is where the evidence goes.
# Definition of done
Inputs: the spec's Done When lines, the team-wide list, the change.
Outputs: every line marked checked with evidence, or "not checked".
## Team-wide (every job)
[ ] Tests pass (name them), none skipped or removed
[ ] Lint and type checks pass
[ ] No secrets or personal data in the diff
[ ] Reviewed by [person or agent]
[ ] Checked on staging, not just locally
[ ] Deployed to production and checked there (or marked: merged, not checked)
[ ] The spec still matches what was built
[ ] [Anything your team has been bitten by]
## Done When (this job)
1. Given [state], when [action], then [result].
Evidence: [test name | staging URL | link], [what was checked], [date]
2. Given [state], when [action], then [result].
Evidence: [test name | staging URL | link], [what was checked], [date]
3. Given [state], when [action], then [result].
Evidence: [test name | staging URL | link], [what was checked], [date]
## Status
Done only when every line has evidence. Otherwise: not done, and name the unchecked lines.
How do I fill it in?
The team-wide list. About 5 to 8 lines that apply to every job: tests pass, lint passes, no secrets in the diff, reviewed, checked on staging, deployed to production and checked there, the spec still matches what was built. Add only what your team has been bitten by. A long list gets ignored.
Keep the list where every agent reads it: your rules file. The AGENTS.md template has a place for it. Add one instruction beside it: "Before you say a job is done, check every line and say how you checked it."
Done When lines. These come from the spec for the job. Write each as "Given [starting state], when [action], then [result]". If you cannot check a line, rewrite it. Compare with acceptance criteria, which are the same idea, written for a person to test.
Evidence per line. For every line, record one of: a test name that covers it, a staging URL where you can see it, or a link someone can follow. Write what was checked and the date. A line with no evidence stays unchecked, and you say so.
What counts as evidence?
- A test that fails without the change and passes with it
- A staging page or screen you can open
- A log line or database row, with how to find it
- A screenshot with the URL and the date
- Nothing counts if only the author can see it
Not evidence: "it works on my machine", "the tests pass" without naming which, or a merged pull request.
Who checks?
The agent records what it checked. A person looks at the lines that matter most, such as anything customer-facing. For more on this with agents, see definition of done for AI agents.
An example, filled in
This is an example, made up to show the level of detail. Say the job is "Send a monthly summary to a client".
Done When
- Given a project with 5 finished items in October, when I pick October, then the summary lists those 5 items with dates.
- Evidence: tests/summary.test.ts "lists finished items for a month", passing on 21 Oct.
- Given a summary, when I enter a client email and send, then the client receives it within a minute.
- Evidence: staging email to a test address, received 14:03. Link to the message in the test inbox.
- Given a month with no finished items, when I pick it, then I see a message and no email is sent.
- Evidence: not checked yet.
Team-wide
- Tests pass: summary tests named above
- Lint and type checks pass
- Reviewed by a second agent
- Checked on staging: lines 1 and 2 only
- Deployed to production and checked there: merged, not checked
Status: Not done. Line 3 has no evidence, and nothing is checked on production yet.
The point is the last line. A job with one unchecked line is not done, and the checklist says so plainly instead of letting it slide.
What mistakes should I avoid?
- Calling merged done. Merged means the code is in. It does not mean it works for the customer.
- A line you cannot check. "Fast enough" needs a number.
- Evidence only the author can see. If nobody else can follow it, it is a claim.
- A giant team list. 8 lines people read beat 40 they skip.
- Counting an unchecked line. Say it is unchecked. Never tick it to look finished.
- Never updating the list. When something slips through, add one line.
To fill this template, an agent takes the spec's Done When lines and the team list, and returns each line with its evidence or the words "not checked".
How does Annsa do it?
In Annsa, the Done When lines live on the spec for each priority. Your agent records evidence against each line over MCP, as it checks it, with a followable link. A line with no evidence stays unchecked and is shown that way. An unchecked line is labeled on the spec and the call is yours, and a person releases to production. Annsa never deploys. See how Done When works and the spec template that comes before it.
