Write the check first

"Done" is the emptiest word in software. It usually means the code merged. It almost never answers the two questions that matter: what changed for the person this was built for, and how would anyone check?

The practice I hold myself to is simple to state. Before building anything that matters, I write three things down. Who the work is for - a specific person in a specific situation, not "users." What changes for them - their before and after, in their terms, not mine. And the check that would prove it - a concrete observation that says the change happened, written so that it can fail. Then I build. The claim starts as proposed and only becomes proven when the check passes against the real, shipped thing.

The order is the whole point. A check written after shipping is a defense - you already know the outcome, and everything you write bends toward justifying it. A check written first is a target. It's the difference between a scientist stating what would falsify the hypothesis before the experiment and one explaining the data afterward. If you can't name the observation that would break your claim, you don't have a claim. You have a slogan.

Writing it first also forces scope honesty. When the check is on paper before the work starts, you find out early that half the plan doesn't serve it - and you get an explicit list of what you're not promising, which is worth as much as the promise. Every contract I write carries an anti-scope: the things stakeholders might have wanted that this work deliberately doesn't do. Naming the tradeoff up front beats being caught not having made it.

A worked example

This website is the nearest example, because you're on it. Before any page was built, its contract said, roughly:

Who it's for: the person deciding whether to take me seriously as a builder

• an investor, a hiring partner, a reporter, a fellow engineer - who just searched my name and landed here. Not "visitors." One person, mid-evaluation.

What changes: before, they assemble a fragmented and partly wrong picture from profile fragments and third-party pages, and either misjudge me or give up. After, they land on one page and within one read can say what I do, name things I actually built, and act - write to me instead of guessing.

The check: hand the live site to five strangers who have never met me. After one read, at least four of five must be able to say in one sentence what I do and name two things I built, without help. Breaks if fewer than four can, or if real inbound over ninety days never references the work by name.

That contract was written while the domain still pointed at a parked page. The site has shipped in stages since, and the claim's status is still proposed - it moves to proven when a cold-read round clears the four-of-five bar against the live site, and not before. Which means I have to be prepared for the honest outcome: the site is live, the essay you're reading is on it, and the contract may still say "not yet proven." That discomfort is the feature. A status line that can say "not yet" is the only kind worth reading.

What happens after the contract

Writing the contract is a quarter of the work. I've watched the other three quarters get skipped enough times to name the ways it dies.

Claims rot. The contract sits at "proposed" for months, nothing gets verified, and it quietly becomes aspirational copy that everyone is slightly embarrassed to point at. Or verification becomes theater: someone wires up an automated judge that grades every claim "good" against vague rubrics, the scorecards exist, they measure nothing, and stakeholders learn to ignore them. Or the team just stops referring to the contract and ships features - the claims become marketing, decoupled from the product.

The antidote is treating the check's infrastructure as load-bearing, on equal footing with the contract. Audit what's actually built against each claim, with evidence, in a hostile-reviewer voice - the audit's job is to find what would embarrass you if a customer did it. Build the smallest harness that can produce a verdict: for a claim about improvement over time, that's a single baseline measurement; for a claim about enforcement, it's one automated assertion that fails if the enforcement regresses. Measure the baseline even when the answer is unflattering - especially then. Then re-measure every release, and publish the delta. One measurement is a data point. Three is a trend. Until the baseline exists, every conversation about whether the work is improving is unmoored.

And prefer checks that are deterministic. A missing file is missing. A failing assertion fails. Same input, same verdict, auditable by anyone, no trust in a grader required. Judgment-based scoring - human or machine - has its place for genuinely semantic properties, but it drifts, it costs, and "scored 6.4 out of 10" invites argument in a way that a red build does not. Default to the check that fails loudly.

Where this can go wrong

The biggest one: writing the check first doesn't make it the right check. There is a standing temptation to write a check you already know you can pass - to measure the part of the value that's convenient rather than the part that's real. The four-of-five cold-read above is a proxy; the value I actually want is a correct read of me by a stranger and real inbound that references the work, and the proxy could pass while the real thing doesn't happen. Two guards help. Write the breaks-if clause with the same care as the promise, so the claim has a named way to die. And let someone who isn't you read the contract cold and tell you what they think it promises - the check is itself an artifact that can fail a stranger's read. Neither guard is proof. A passed check proves the claim as written, not that the claim was worth making.

There's also a cost line. A contract with a harness and a baseline is real work, and for throwaway work it's overkill. The test I use: will anyone other than me depend on this claim in three months? If no, skip the ceremony. If yes, the ceremony is cheaper than the argument you'll have without it.

I've published the format I use for this as a small standard - one file at the root of a project stating who it's for, what changes, and the check - at keepavalue.com. But the format matters less than the habit. Before you build, write down who it's for, what changes for them, and what you'd accept as proof. If the finished thing can't pass the check you wrote when you were still honest, the thing isn't done. It's just merged.