Acceptance criteria written so that done is a fact, not an argument
Most delivery disputes are not about quality, they are about whether the work is finished. Acceptance criteria written before the build make that a matter of record rather than opinion.
By Laurent TulpanPublished 8 min read
Write down, before anything is built, what a person will do and what must happen for each critical process, and who checks it. That one page settles the question every software project ends on: is it finished? Without it, both sides argue in good faith from different definitions, and nobody can win, because nobody is wrong.
The meeting where nobody is lying
Picture the last week of a project. The vendor has built a tool that produces quotes, and it produces quotes. The vendor says it is done.
The sales manager says it is not. It cannot handle the customer with the negotiated discount grid, and that customer is a fifth of the revenue. The vendor answers that the discount grid was never in the specification.
Both are telling the truth. That is what makes the meeting so bad.
The specification described the main path, because the main path is what everybody can put into words. The special cases live in people’s habits, and they surface the moment real work goes through the system. This is not bad luck. It is the normal shape of software delivery.
Acceptance criteria do not make the surprises go away. They decide, in advance, which surprises are inside the scope and which are a change. Finding one then becomes an ordinary event with a known next step, instead of a confrontation about who should have known.
What a usable criterion looks like
Three properties, and a criterion needs all three.
- Somebody other than the builder can run it. If checking it requires the developer’s knowledge, it is a demonstration, not acceptance.
- The result is binary. It passed or it did not. No “mostly”, no “broadly works”.
- It describes an action and an outcome, not a quality. What a person does, and what has to happen next.
The difference is easiest to see side by side.
| Criterion as usually written | Why it cannot be accepted | The same criterion, testable |
|---|---|---|
| The quoting module must be reliable and fast | Nobody can fail it, so nobody can pass it | A salesperson, alone, with the user guide, produces three real quotes including one with a negotiated discount, each in under ten minutes |
| Customer data is migrated | Migration always reports success | A named person checks thirty records drawn at random against the source, and the totals match |
| The system is documented | Documented for whom, and to do what? | Our administrator, alone, follows the documentation and redeploys the system on a clean server |
The right-hand column is longer, and that length is the point. Every word in it is something that could otherwise have been argued about.
The four criteria nearly always missing
These are the ones whose absence turns a delivery into a dispute. We usually discover them by arriving after the fact.
The degraded path. The customer is not in the database. The product has left the catalog. The approval never arrives. Specify only the happy path and you are guaranteed a system that meets its specification and cannot be used, because real work is mostly edge cases.
Migration, verified rather than performed. Not “the data are migrated” but a two-pass check: automatic on volumes and totals, manual on a random sample, by a person whose name is on the page.
Restoring, not backing up. The backup runs on delivery day. Whether it restores is a different question, and it belongs in the acceptance of any system holding data you cannot recreate. The distinction is the whole subject, and it is the criterion most often assumed rather than tested.
Somebody else deploys it. Not the vendor demonstrating the deployment: your person, alone, following the documentation, while the vendor watches and keeps their hands in their pockets. Whatever is missing surfaces within the hour, and something always is. This is what turns a handover into a fact, and it is the same exercise that reduces key person risk.
Two clauses that make acceptance signable
Acceptance often stalls not because the software is bad, but because signing feels like giving up your rights. Two clauses remove that fear.
A correction period after acceptance. Thirty, sixty or ninety days during which defects against the agreed scope are fixed at the vendor’s cost. Acceptance then means the scope is delivered, not that the software is perfect, and that difference is what makes a signature possible.
A named arbiter and a deadline for qualification disputes. When the two sides disagree whether something is a defect or a change, somebody decides within a stated number of days, and the correction carries on meanwhile. Keeping the operational urgency apart from the commercial argument stops a disagreement from turning into a standoff. It is the same clause that keeps a maintenance contract workable once the build is over.
A system nobody has formally accepted is not a delivered system. It is a dispute that has not started yet.
The rehearsal that prevents most of it
Before acceptance is scheduled, run one session with real users on real data, with one instruction: try to break it.
Not a demonstration. A session where finding a problem counts as a success, where nothing is at stake, and where nobody has to defend anything.
It pays twice. The defects found there get fixed before the formal acceptance, which is what everybody wanted anyway. And the users arrive at acceptance having already used the system. They are testing, not discovering, and a person discovering a system for the first time will reject it for reasons that have nothing to do with the contract.
The one-page format that is enough
For each critical process: what a person does, what must happen, and who verifies it. Here is what three rows look like for a quoting and invoicing tool.
| What a person does | What must happen | Who verifies |
|---|---|---|
| A salesperson creates a quote for a customer with a negotiated discount | The discount is applied without manual override, and the quote is ready in under ten minutes | Two salespeople, on three real customers each |
| Accounting converts a signed quote into an invoice | The invoice carries the same lines and totals, with no retyping | The accounting lead, on ten signed quotes |
| The administrator restores last night’s backup on a spare server | The restored system opens and shows yesterday’s quotes | The administrator, with the vendor watching |
Five to fifteen rows covers most business software. That page is worth more than thirty pages of functional specification, because it is the only part anybody can hold you to, in either direction.
It belongs in the request for quotes, not in a document produced afterwards. A vendor pricing against a defined finish line quotes tighter, which is a property of the requirements document more than of the negotiation. If you want a second pair of eyes on yours before it goes out, that is part of how we run custom software development on a fixed fee.
Further reading
- Writing requirements that produce comparable quotes: where these criteria belong
- Your backups run. Do they restore?: the criterion most often assumed
- Fixed fee or time and materials: why a defined finish line makes a fixed price possible
- When one person is your only backup: the deployment rehearsal, in another context
The questions this raises, answered straight.
What makes an acceptance criterion testable?
Somebody other than the person who built it can perform it, on their own, and the outcome is not open to interpretation.
Three real quotes produced by a salesperson, each in under ten minutes, timed, is testable. The system must be user-friendly is not, because nobody can fail it and therefore nobody can pass it.
When should acceptance criteria be written?
Before the build, and preferably before the quote.
Written afterwards they become a negotiation, since each side now has an interest in where the line falls. Written before, they tighten the vendor's estimate, because a defined finish line is the thing that makes a fixed price possible at all.
Who should run the acceptance tests?
The people who will use the system, not the project sponsor and not the vendor.
A sponsor tests the demonstration path. A user finds the case that breaks it, because they know which customer has the unusual arrangement.
Budget their time explicitly, because unbudgeted acceptance testing is the step that gets compressed when the schedule slips.
What if a defect is found after acceptance?
That is what the correction period is for, and the contract should carry one.
Acceptance is not a claim that the software is perfect, it is a statement that the agreed scope is delivered. Confusing the two makes acceptance impossible to sign, which is how systems end up running in production for months without anyone having formally accepted them.
Recognize your situation? 20 minutes is enough to tell.
Describe what is happening on your side, and where your data and customers are. You get a plain answer on whether we can help, and a better route if there is one.