11  Principle One — Spec In, Evidence Out

The deepest habit in regulated clinical work is that intent precedes action and leaves a record. The protocol says what the analysis will do before the analysis does it. The mock shell says what the table will look like before the table exists. The statistical analysis plan is signed before the first model is fit. Regulators do not demand this because they love documents; they demand it because a result that was specified in advance cannot quietly morph into whatever the data made convenient.

Modern software practice has independently rediscovered the same idea: specification-driven development, infrastructure as code, “everything as code.” The synthesis for clinical reporting is a pipeline with a hard grammar: spec in, evidence out. A machine-readable specification enters the system. What exits is not merely the deliverable — dataset, table, figure, report — but the deliverable welded to its evidence: the hash of the spec it satisfied, the lineage of the data it consumed, the comparison that verified it, the manifest that makes the whole bundle replayable.

11.1 The spec is a first-class artifact

Treat the specification with the same seriousness as the output. Concretely, that means the spec is versioned, hash-addressed, and stored alongside the result — not emailed, not embedded in a Word file with track changes, not living only in a ticket tracker. A spec that cannot be referenced by identity is a rumor of intent.

The practical payoff is subtle but enormous: traceability becomes a lookup, not a study. When an auditor asks “which outputs were affected by this analysis-population change?”, the answer is a query over the graph — every artifact whose lineage includes the changed spec — instead of a week of reading program headers.

11.2 Consequences for design

Specification-first imposes disciplines that pay for themselves:

• Mock before meaning. A table shell — layout, columns, headers, footnotes, but no numbers — is a spec two stakeholders can argue about cheaply, before a single analysis hour is spent. The most expensive bug in clinical reporting is the correctly computed table nobody wanted.
• Parameters, not edits. When a study changes, the spec changes and the system re-executes. Programmers editing code in response to data changes is how drift begins; drift is how specifications stop describing reality.
• Ambiguity must fail loudly. If the spec cannot fully determine the output, the correct behavior is a routed question to a human, never a silent default. A system that guesses has converted an ambiguity into an unrecorded decision — the exact species of error this whole apparatus exists to prevent.

11.3 What it feels like

Teams that adopt spec-in/evidence-out report a phase change. Early on, writing specs feels like bureaucracy — why describe the table when I could just build it? Then the first re-execution happens: a data cut arrives, one command re-renders forty outputs, every comparison runs, and the meeting that used to take a week takes an hour. From that point the spec is not overhead. It is the product; the outputs are prints.

The test. Pick any delivered output and ask: “Which exact specification, at which version, produced this — and where is that specification right now?” If answering takes more than one lookup, intent and action have drifted apart, and the drift is already compounding.