Agreeing what done means, before anyone starts

Most arguments about whether something is finished are arguments that should have happened at the start, held at the worst possible moment: after the work exists, when changing it costs something and somebody has to be wrong.

The fix is not a heavier process. It is three questions, asked before anyone opens an editor, and answered in the issue where everyone can see them.

Question one: how will we know it worked?

Not "what should it do", which invites a description of the implementation. How will we know. The answer has to be something observable by somebody who did not build it.

The second version is not more detailed for the sake of it. It settles two things that would otherwise be settled during review by whoever felt strongest: that the row count is the test, and that a graceful failure counts as success. Both are decisions. Both were going to be made by somebody. The only question is whether they get made in public, early, by the people who care.

Question two: what is deliberately not included?

Scope is defined by its edges, and the edges are where the disagreements live. An issue that says what it covers but not what it excludes is only half specified, because every reader fills the silence with their own assumption and none of them notice they have.

One line is usually enough.

This is also the cheapest way to find out you disagree. If somebody objects to the exclusion list, they were carrying a different picture of the work, and you have just discovered it for the price of one sentence instead of one sprint.

Question three: who decides?

The question nobody asks, and the one that determines whether the other two hold up.

When the work turns out to be harder than expected, or a case appears that nobody considered, or the fix would take three days instead of three hours, somebody has to choose. If that person was named at the start it is a five minute conversation. If not, it becomes a thread, then a meeting, then a decision made by whoever is least tired.

Naming one person is not bureaucracy. It is the thing that lets the work continue when the plan meets reality, which it will.

What this is not

It is not a template, and it is not a gate. If you write these three answers into a form with required fields, you will get "N/A" in all three within a fortnight, for the same reason every other required field gets N/A: a question asked by a form is a toll, and people pay tolls as cheaply as possible.

It also is not exhaustive. Three sentences will not anticipate everything, and trying to make them is how you get a specification nobody reads. The point is not to remove surprises. It is to make sure that the predictable disagreements happen while they are still free.

The cheapest version

If three questions is two too many, ask the first one. "How will we know it worked?" is worth more than the other two combined, because an unanswerable version of that question is the clearest possible signal that the issue is not ready, and it is a signal anyone can read.

An issue that cannot say how you would know it worked is not a small issue or a vague issue. It is an issue where nobody has yet decided what the work is, and no amount of estimating will change that.