7 October 20257 min read
Almost every unpleasant conversation in an outsourced engagement is the same conversation. The work was delivered, the invoice arrived, and one side thinks the item is finished while the other does not. Neither is being dishonest. They are applying two different standards, both of which are perfectly reasonable, because nobody ever wrote one down.
A definition of done is the cheapest document in software. It is usually one page, it takes an afternoon, and it removes the entire category of argument it covers.
Why "done" is where engagements fail
In a team that has worked together for years, done is a shared instinct. Everyone knows the change is not finished until it has a test, has been reviewed, has a note in the changelog, and has been checked on staging. Nobody says it, because nobody has needed to say it since the second year.
Bring in someone from outside, and that instinct is not transferred with the ticket. They have their own instinct, formed on other systems with other standards. When the two disagree, it surfaces at the worst possible moment: at acceptance, with a deadline behind it and money attached. The argument then feels like a dispute about competence, when it is really a dispute about an unwritten rule.
This is not specific to outsourcing. It is specific to anyone who has not absorbed your habits by sitting next to you for a year, which includes every new employee too. Outsourcing just makes it happen sooner and with an invoice involved.
It is a contract with your future self
The reason to write it is not to hold a vendor to account. It is to force your own team to decide what it actually requires, before there is any pressure to say yes to something that is nearly finished.
That is the uncomfortable part. Most teams discover, halfway through writing their definition of done, that they do not agree internally. One person believes every change needs a test, another believes tests are for the parts that break, a third has never thought about it. That disagreement was always there, silently generating inconsistent review standards. The document does not create the problem, it exposes it, and that is most of its value.
What belongs in it
Keep it to things that are checkable by a person who was not in the conversation. If two reasonable people could look at the same change and disagree about whether a line is satisfied, the line is not finished.
- The code is reviewed and approved by someone other than the author.
- Automated checks pass on the branch, and the list of what counts as a check is named, not implied.
- Tests exist for the behaviour the ticket describes, at whatever level your team actually uses.
- It has been exercised on staging against realistic data, by someone, and that someone is named in the ticket.
- Anything a user or another engineer needs to know is written down: release notes, an updated README, an architecture note, whichever applies.
- Feature flags, migrations and configuration changes are described, including how to reverse them.
- Errors and logging exist for the failure paths, not only the happy one.
Seven lines is a lot. Five is more likely to survive. The document that gets followed is short enough that someone can hold it in their head while reviewing.
What does not belong in it
Acceptance criteria for a specific ticket are not part of the definition of done. Those describe what this piece of work must do, they change every time, and they belong in the ticket. The definition of done describes what must be true of every piece of work regardless of what it does. Mixing the two produces a document that is either enormous or useless.
Aspirations do not belong in it either. If you write "performance is measured and does not regress" and nobody has ever measured performance on this system, you have not raised the bar. You have written a line that gets skipped every time, which teaches everyone that the document is decorative.
Neither do things you cannot check remotely. A criterion that depends on someone walking to a desk is not a criterion in a distributed team.
One definition per team, not per ticket
Some teams try to grade the standard: light for small changes, full for large ones. This is reasonable in principle and collapses in practice, because the grading itself becomes the argument. Everyone believes their own change is small.
One standard, applied to everything, with explicit and written exceptions when you genuinely need to ship something at two in the morning. The exception being visible is the point. A standard that quietly bends is not a standard, and a distributed team cannot tell the difference between a bend and a rule until it has watched you for six months.
The acceptance conversation
With a definition of done in place, acceptance stops being a judgement and becomes a comparison. Either the checklist is satisfied or it is not, and if the answer is that it is satisfied but you are still unhappy, that is genuinely useful information: your definition of done is missing a line, and you have just found which one.
Add the line. Do not add it retrospectively to the invoice you are currently arguing about. Take the loss on this item, change the document, and it will not happen again. Trying to apply a new rule to work that was completed under the old one is how goodwill is spent, and goodwill is what makes the next difficult conversation cheap.
Review the definition, not just the work
Look at the document once a quarter with both sides in the room. Two questions: which line have we skipped most often, and which problem reached production despite the list. The first tells you which line is unrealistic and should be cut or changed. The second tells you what is missing.
A definition of done that has not changed in a year is either extremely well written or, far more likely, not being used. It is a working tool for the way this specific team builds this specific system, and both of those keep moving.