The test ran. It printed green. You saw it happen. Then you merged, closed the task, and moved to the next one, and the green scrolled up out of the terminal and was gone. Three weeks later something breaks nearby and you cannot answer a basic question: did that test ever actually pass, and against which version of the requirement? The proof existed for about four seconds and then you threw it away, the way almost every workflow throws it away.
Evidence-based development is the small, boring discipline of not throwing it away. Close the work with the proof attached.
Status is not evidence
Start with a distinction that most tools blur on purpose. A completed checkbox, a merged pull request, a green badge, these are status. They tell you a state was declared. They carry almost no information about whether the underlying thing is true, because they are trivially easy to set without the thing being true. A checkbox is one click. A green badge can sit on top of a suite that never ran.
Evidence is different in kind. Evidence is what actually happened, recorded: the command that ran, the output it produced, the version of the contract it ran against. You can inspect evidence and reconstruct the truth from it. You cannot reconstruct anything from a checkbox except that someone, or something, checked it. The same distinction governs how product decisions should be made, not just how code is closed.
The gap matters most exactly when you can least afford it: when the author was a model and nobody watched every line. A human author carries the context in their head and can be asked. A model produced a plausible artifact and moved on. The only durable account of whether it works is the evidence you captured, because there is no author to interrogate later. This is the same reason a false success claim is so dangerous. “Tests pass” as a sentence is status. “Tests pass” as a captured run against a named contract is evidence. They read alike and they are not the same.
status
- a checked box
- a merged PR
- a green badge
evidence
- the command run
- its real output
- the contract version
What to capture, and where it lives
Evidence-based development is concrete, not a philosophy. For a unit of work, capture:
- What ran. The actual commands and invocations, not a summary of them.
- What it produced. The output and exit codes, as they came out, not compressed into “looks good.”
- Against which contract. The acceptance criteria, at the revision they were at, so a green cannot silently drift to referring to yesterday’s requirements.
And then the part everyone skips: put it somewhere it survives. Evidence that lives in a terminal scrollback, a CI log that ages out, or a chat transcript you will never scroll back to is evidence you do not have. It has to attach to the change, travel with it, and be findable by the next person and the next agent without archaeology. Proof you cannot retrieve is indistinguishable from proof you never had.
This is why a specification is only half of what you need. A portable specification carries the intent and the contract; the evidence is what proves the contract was met, and it has to travel in the same envelope or the spec is a promise with no receipt.
Evidence has a shelf life, and that is a feature
A common objection: evidence goes stale. The test passed against version 3 of the contract, the contract is now on version 5, so the captured green no longer proves anything. True. And it is exactly why evidence beats a bare checkbox instead of sharing its weakness.
A checkbox that goes stale stays checked. It carries no version, so nothing about it announces that it is now lying. It looks as valid on the day it went obsolete as it did the day it was earned, which is the worst property a status can have. Evidence that names the contract version it ran against goes stale visibly. When the contract moves to version 5, a run recorded against version 3 is self-evidently in question, and the system can flag it: this proof refers to requirements that have since changed, re-verify before trusting.
That is not evidence failing. That is evidence doing the one thing status cannot, telling you when it has stopped being true. Staleness you can detect is a solved problem, you re-run and re-capture. Staleness you cannot detect is how a codebase fills with greens that refer to a world that no longer exists. Capturing the contract version alongside the run is what converts the first situation into the second, and it costs nothing but the discipline of recording which version you checked against. This is the same reason a specification and its proof have to travel together: a contract that moves while its evidence stays behind is a promise nobody can audit.
Evidence is what makes trust cheap
Here is why this pays for itself. Without captured evidence, trusting the state of the system means re-establishing it by hand every time you need it. Does this still work? Better re-run it. Did that ever pass? Better check. Every question about the past becomes a fresh verification in the present, and with agents producing at volume, the questions never stop.
With evidence attached, the past answers its own questions. You open the record instead of rebuilding it. That is the difference between a system whose trustworthiness you have to keep re-earning and one whose trustworthiness you can look up. It is the practical form of trust, not output, being the bottleneck: evidence is what turns trust from a recurring cost into a stored asset. It is also what makes the assurance station able to keep pace, because assuring a change that arrives with its proof is a read, not a re-run.
Evidence closes the loop that “done” opens
This connects directly to what completion means. If done requires a demonstration, the demonstration is exactly the evidence, and evidence-based development is just the insistence that the demonstration doesn’t evaporate the moment the task closes. Completion produces the proof; evidence-based development keeps it. One without the other is half a loop. Demonstrating done and then discarding the demonstration leaves you trusting a memory of a green you can no longer see.
The reviewer feels this too. When work closes with its evidence attached, the last and most important review step, checking what actually ran, is reading a record rather than reconstructing one, which is a large part of the way out of review fatigue.
Where PaellaDoc fits
PaellaDoc captures evidence as a byproduct of the work rather than as a separate chore nobody does. When a task closes, what ran, what passed, and the contract it ran against are recorded next to the change, not left to evaporate in a terminal. The state of the system stops being something you trust on faith or re-verify by hand, and becomes something you can open and read.
There is a cultural shift buried in this, and it is worth saying plainly. Attaching evidence feels like extra work in the moment, and the moment is always busy, so it is the first thing dropped under pressure. That instinct is backwards. The evidence you skip capturing today is the manual re-verification you sign up for next week, with interest, at the worst possible time, when something is already breaking and you are trying to reconstruct whether it ever worked. Capturing proof is not overhead on top of the work. It is the work, deferred or done, and deferred is always more expensive.
The models will keep producing plausible artifacts at a rate no human can re-check. Attaching the proof, and keeping it, is how you stay able to trust the system without auditing it from scratch every time you look.
Frequently asked questions
What is evidence-based development?
It is the discipline of closing every unit of work with its proof attached: what ran, what it produced, and against which version of the contract, stored where the next person and the next agent can find it. It exists because most workflows keep the diff and throw away the proof, the green scrolls out of the terminal and vanishes. When the author is often a model nobody watched line by line, captured evidence is the only durable account of whether the work works.
What is the difference between status and evidence?
Status is a completed checkbox, a merged pull request, a green badge. It tells you a state was declared and carries almost no information about whether the underlying thing is true, because it is trivially easy to set without the thing being true. Evidence is what actually happened, recorded: the command that ran, its real output, the contract version. You can reconstruct the truth from evidence; from a checkbox you can only reconstruct that someone checked it.
What should I capture as evidence for a completed task?
Three things, plus a place to keep them. The actual commands and invocations, not a summary. The output and exit codes as they came out, not compressed into “looks good.” And the acceptance criteria at the revision they were at, so a green cannot silently drift to yesterday’s requirements. Then attach it to the change so it travels with it. Proof you cannot retrieve is indistinguishable from proof you never had.
Doesn’t captured evidence go stale and become useless?
It goes stale visibly, which is the point. A checkbox that goes obsolete stays checked and announces nothing. Evidence that names the contract version it ran against becomes self-evidently questionable the moment the contract moves, so the system can flag it: this proof refers to requirements that have since changed, re-verify. Staleness you can detect is a solved problem, you re-run and re-capture. Staleness you cannot detect is how a codebase fills with greens referring to a world that no longer exists.