Why "Done" Is the Most Dangerous Word in Software

Ron Reynolds · 2026-09-02 · 11 min read

Second in the QC series. The deception layer between asserted and tested — and the gate that closes it.

Confidence, unexamined, is a guess.

Every engineer who has ever shipped knows the feeling. The compile passed. The lint is clean. The unit test is green. The PR description reads well. The agent reports success. We say done and we move on, and somewhere underneath the word there is a thin assumption we have not actually tested, holding the whole claim up.

Done is the most dangerous word in software because it hides the gap between what was asserted and what was proven. The gap is small enough to be missed every single time and large enough to ship the bug. The deception layer

Every engineering culture runs on a vocabulary that closes loops faster than the underlying work warrants. Done. Ready for review. Working on my machine. Should be fine. Each of these phrases is a closure ritual — the speaker has decided the work is good enough to hand off, and the receiver is invited to inherit the closure.

The vocabulary is necessary. Software shipping at scale cannot pause for full verification of every claim at every handoff; the throughput would collapse. So we trade verification for trust, and the trust is calibrated to whatever the speaker believes about the work at the moment of handoff.

The problem is structural. The speaker's belief about the work and the work being correct are two different things, and they diverge in eight recognizable channels — the eight canonical places where what an agent (human or machine) believes about their work drifts from what the work actually does. The count in the prose doesn't match the items in the list. The assertion this is correct rests on a verification that doesn't reach the assertion. A magic number repeats across several call sites with no rationale at any of them. A string key gets composed inline in place after place with no shared encoder. The scope of what the work doesn't solve was never written down. The verification floor — the test that actually ran — doesn't match the strength of the claim above it. The opening sentence sells what the author wished they had built. The test fixtures were invented by the author, so the suite agrees with the author's premise rather than with reality.

Any one of these, in isolation, is a small flaw. The combination of all eight, live on every "done" event, is the substrate of every shipping bug, every onboarding misunderstanding, every audit finding, every post-mortem.

Each channel is a place where the speaker's belief outran the work. Each channel is a place where done was a guess wearing the costume of a fact. What the eight questions actually do

QC's final inspection is an eight-question gate. Run before any "done" claim survives: Q1: Does my count match my list? Q2: Did I test what I asserted, or did I assert it? Q3: Are my magic numbers justified at the call site? Q4: Are my string-encoded keys schemaed? Q5: What does my work NOT solve? Q6: Does my verification floor match my claim? Q7: Is my framing honest about what I did? Q8: Did the verification's inputs come from reality, or from me?

Each question is a different kind of did you actually. Each targets one channel where assertion drifts from evidence. None of them asks is this good? — a question too coarse to answer. They ask did the specific thing you said, actually happen, in the specific way you said it.

The questions look mechanical because they are. That is the point. A mechanical question fires the same way every time; the speaker cannot talk it out of firing. The cost of running it is small. The cost of skipping it is the bug that ships.

Q6 is the hinge. Does my verification floor match my claim? If the test you ran was tsc --noEmit and the claim you wrote was behavior is correct, the floor doesn't reach the claim. Type-checking proves the types are consistent, nothing more. The honest move is to downgrade the claim to types are consistent or strengthen the test to one that actually exercises the behavior. Either move closes the gap. Saying behavior is correct on the strength of a type-check is the polite engineering version of guessing.

The eight questions convert confidence from an emotional state into a measurable property. Did the verification floor reach the claim, yes or no. The answer is checkable. The guess becomes a fact, or the claim gets honest about what it is. The asymmetry

Asserted is not tested. Tested is not proven. The three are arranged in a hierarchy that most engineering vocabulary collapses into one word — done — and the collapse is where bugs live. Asserted. The author wrote a sentence claiming the work is correct. Tested. A test ran and reported a green result. Proven. The strength of the test matches the strength of the assertion — and the test's inputs came from reality rather than from the author's imagination.

The first level is free. Anyone can write a sentence claiming anything. The second level costs minutes — write a test, run it, watch it pass. The third level costs attention: read the assertion, read the test, ask whether the test actually exercises what the assertion claims, ask where the fixtures came from, downgrade the claim or strengthen the test until the two meet.

The third level is where most engineering culture runs out of energy. The test passed; the box is checked; the work moves to done. But the assertion was a property claim and the test was a syntax check. The two never met. The work is asserted-and-tested without being proven. It will ship. It will surface as an incident.

Q6 forces the third level to be the closure event, and Q8 guards its inputs. If the floor doesn't reach the claim, you have two honest moves and one dishonest one. Strengthen the test until it reaches. Downgrade the claim until the test reaches it. Or pretend the gap isn't there and call the work done. The first two are operational. The third is the deception that ships bugs.

The eight questions cover the eight kinds of asymmetry between belief and work. They do not make the gap go away. They make the gap visible at the moment of closure, which is the only moment at which the gap is cheap to close. Why this gets worse with AI

A human who says done has, at minimum, lived inside the work. They have a body sense of what they did, even if they overstate the result. The body sense is unreliable but it is not zero.

An AI agent that says done may have no body sense at all. The agent generated text asserting completion because its training distribution suggested that text was the right shape to produce after a successful tool sequence. The assertion is a stylistic completion. The gap between the words the agent produced and the state of the system is wider than the gap between human assertion and reality — and the agent has no instinct that something is off, because the instinct is the body sense the human still has.

This is the structural reason coarse engineering discipline fails on AI-assisted work. Looks good to me and the build passed and tests are green are the closure rituals the agent has been trained on. The agent will reproduce them at the right moment in the workflow because that is the shape of the training distribution. None of those rituals reach the claim being made.

QC works on AI agents because the eight questions are mechanically structured and the agent can run them. The agent does not need a body sense to ask does my count match my list. The agent counts. The agent compares. The agent reports the gap. The gate fires the same way for the human and the machine — whether the closure ritual feels complete or not.

This is what makes the gate the right shape for mixed-species work. The discipline does not depend on the species of the participant. It depends on the participant running the gate. What changes when "done" stops being a guess

Three things happen in a corpus where the eight-question gate fires on every closure event.

1. Bugs surface at the moment of closure rather than the moment of incident. A bug caught by Q6 at the end of the prompt that produced it costs a minute. The same bug caught by an incident two weeks later costs the incident response, the rollback, the post-mortem, the trust hit with the customer, and the next two weeks of being careful for the wrong reasons. Compounded across thousands of artifacts, the difference is the difference between a system that holds shape and one that rots.

2. The vocabulary recalibrates. Engineers stop saying done and start saying the verification floor is the integration test on the staging env; it caught nothing; I am calling this done at that floor. The sentence is longer. It is also a different category of speech act — a measured claim with the measurement attached. The vocabulary shift is small. Its effect on what gets shipped is structural.

3. Trust gets cheap. When every done in the corpus has passed through the gate, the receiver does not need to re-verify the speaker's belief. The receiver inherits a claim with the verification floor named. The handoff cost drops. The trust the receiver extends stops being a personal favor and becomes a structural property of the corpus.

That property extends to how the corpus talks about itself. Ask the ComOS corpus a question over its live introspection surface and the answer arrives either cited — every referenced path resolved through a pinned manifest, every quoted excerpt verified against the artifact it cites — or uncited, labeled as such with the reason. The response shape has no slot for a confident answer with nothing under it. The deception layer this article is about is a layer the corpus is built to refuse, and you can check that without asking us. The artifact, installable

The skill is open source:

https://github.com/ronrey/proof-before-done

The canonical SKILL.md, the eight questions, the anti-pattern table, and installation guidance for any AI-assisted codebase live there. If you want to test whether done in your codebase is currently a guess, install the gate and watch the first week of artifacts. The eight questions will tell you, for each done event, whether the verification floor reached the claim — and the gaps that surface will be the bugs your previous closures were hiding.

You do not need to take this on faith. The skill is small enough to install in an afternoon. The first artifact through the gate will show you whether the gap was real. The stealable line

Asserted is not tested. Tested is not proven. Match your verification floor to your claim.

That is the operational heart of why done is dangerous and why the gate works. The three words — asserted, tested, proven — name the three levels engineering vocabulary collapses into one. The gate keeps them distinct at the moment of closure, which is the only moment at which the distinction is cheap to enforce. Next in the series: why the cure is cheap when the cause is close. Closing test [ ] A staff engineer unfamiliar with this article can read it and identify its central claim: that done collapses a three-level hierarchy (asserted → tested → proven) into one word, the collapse is where bugs live, and the eight-question gate — Q6 matching floor to claim, Q8 guarding the inputs — keeps the levels distinct at the only moment the distinction is cheap to enforce. [ ] The central claim is verifiable by named procedures: Q6's mechanism is demonstrable by installing the open-source skill and running it against a "done" claim whose verification floor (e.g. tsc --noEmit) does not reach its assertion (e.g. "behavior is correct"); the corpus-level claim is testable by querying the live introspection surface and confirming every answer arrives cited-with-verified-excerpts or uncited-with-reason. [ ] If a procedure has not been performed, its checkbox stays unchecked until it has — QC is the gate, not the goal.