Specification Is a Compile Target

For most of my career, the specification was the cheap part. You wrote a paragraph, maybe a ticket, and the expensive, skilled, irreplaceable work happened downstream: turning that paragraph into correct code. The spec was a suggestion. The implementation was the truth.

That ratio has inverted, and almost nobody has repriced their work to match.

When an agent can take a precise description of a change and produce a working, tested implementation in minutes, the implementation stops being the bottleneck. It stops being where the skill lives. The skill moves up, to the only place left that the machine cannot do for you: deciding what to build, and stating it precisely enough that the rest is mechanical. The senior engineer doesn’t disappear. They get pushed one rung up the ladder, onto the specification.

And here’s the part the tooling hasn’t caught up to: if implementation is now a compile step, then the specification is a compile target. It’s no longer prose you hand to a human who will fill the gaps with judgment. It’s a source artifact that gets compiled into a system. And like any source artifact fed to a compiler, it deserves a type checker, a linter, and a build that fails when the input is wrong.

That’s the whole thesis. The rest of this series is what it looks like when you take it literally.

What “compile” actually demands

A compiler is unforgiving in a specific, useful way. It doesn’t ask whether your program is a nice idea. It asks whether your program is grounded: do these symbols exist, do these types line up, does this call match a real signature? It refuses to proceed when the answer is no. The refusal is the feature. A compiler that warned politely and emitted a binary anyway would be useless.

Apply that standard to a product specification and most of them fail instantly. A typical spec is full of claims about reality: “the API already returns this field,” “this is just a UI change,” “the consumer can handle the extra parameter.” Each of those is a claim that is either true or false against an actual codebase, and almost none of them are checked. They’re asserted in a planning doc, they survive review because they’re plausible, and they detonate three weeks later in implementation when someone discovers the field was never there.

When a human wrote the implementation, this was survivable: the human caught the lie while coding, cursed, and patched the spec in their head. When an agent writes the implementation, the lie goes straight through. The agent trusts the spec. The spec was wrong. Now you have a confidently wrong system, built fast.

Take the shape of a failure I see constantly. A draft spec claims the system already contains a dormant mechanism for the thing you’re about to build (there’s a flag, or a commented-out block, or a function whose name matches exactly), and the proposal is, essentially, it’s already there, just switch it on. Plausible. The symbol exists; a lazy check (does the name appear in the code?) passes. But a gate that refuses to accept name-matching as evidence opens the body instead, and finds that the code with the right name does something unrelated: it guards a different resource, at a different layer, than the claim assumes. Right name, wrong thing, and an entire workstream would have been built on it. When you force every claim to a citation and re-read it in context, the ones that fail are almost never absurd inventions. They’re plausible claims that happen to be true about a different part of the system.

So the first thing a spec-as-compile-target needs is the compiler’s core move: a blocking gate that refuses to admit an unverified claim. Not a reviewer who might notice. A gate that demands evidence: grep it, cite the file and line, or the claim doesn’t enter the spec. I’ll spend a whole piece on this one, including what a leak rate of unverified claims looks like when you actually measure it, and why the interesting failures aren’t lies but layer confusion — claims that are true, but true about the wrong layer of the system.

The cell nobody is standing in

Here’s the uncomfortable, and I think defensible, claim: I looked, and almost everyone is building the compiler one floor too low.

The spec-driven-development movement is real now. GitHub’s Spec Kit, AWS’s Kiro, Tessl — there’s a credible map of who occupies what, and it’s worth reading. Some of them even have a gate at the spec layer, which is more than I expected when I went looking. Kiro walks you from requirements to design to tasks and checks the requirements document as it goes. Spec Kit ships a Review & Acceptance Checklist you validate before generating.

So the room isn’t empty. But look at what those gates check, because that’s the whole point. Kiro’s spec gate flags ambiguity, internal inconsistency, incompleteness, wrong level of detail. Spec Kit’s checklist asks whether the spec is complete and well-formed. These are real, useful checks, and every one of them is a coherence check. Is the document self-consistent? Is it complete? Does it contradict itself?

None of them asks the other question: is it true? Does “the API already returns this field” survive contact with the actual API? None of these tools grounds the spec’s claims about reality against the actual codebase before it generates. Spec Kit’s reality check runs after implementation: it compares the built code back to the spec, which is a fine thing to do and the opposite of what I’m describing. The grounding research that does verify against source (2026 papers with blocking gates, typed evidence, mechanical citation-checking) operates one floor down, on code and retrieved chunks, not on requirements. The design-system tooling grounds the implementation in real components. The render oracles judge the output.

That’s the room that’s actually empty, and it’s a sharper room than “nobody has a spec gate.” Everyone who reached the spec layer built a coherence oracle. Almost nobody built a truth oracle for the spec: a gate that refuses a requirement because its claim about the existing system is false. “Refuse my spec when it’s lying” — not “when it’s vague.” That distinction between coherence and truth turns out to be the spine of this whole series, and I’ll make it explicit in the next piece.

I want to be honest about why that room is empty, because the flattering explanation is also the wrong one. It’s not empty because it’s a clever niche I alone spotted. It’s empty because it’s early. The hybrid it requires, someone who decides what to build and can engineer the verification of that decision, is rare, and the whole industry’s attention is pointed at automating implementation, which is the thing that just became easy. My bet is that this is temporary. My own argument predicts it: as implementation automates, every senior gets pushed onto the spec layer, and they’ll arrive needing exactly these tools. This series is a playbook written from inside the room, before the crowd arrives.

That’s a bet, not a certainty. “Early” is a synonym for “risk.” The audience that needs a spec compiler today is small, and a fair reader will say this is just good engineering hygiene with grandiose framing. Maybe. I’m writing for the version of you that’s six months from now, standing on the rung you’re about to be pushed onto.

The series: a map, not the territory

What I’ve built is a real pipeline that does this: a compiler for specifications, in daily use on a production codebase. I’m going to give away the map: the frameworks, the vocabulary, the patterns, the reasoning, and the honest numbers. I’m keeping the territory: the actual prompts, the harness wiring, the accumulated rulings, the datasets. The map is what recruits you to the idea. The territory is the part that doesn’t copy out of a blog post anyway.

Here’s what’s coming next:

• The Oracle Lens. Before you can build a gate you need to know what kind of truth it can check. I split verification oracles into three axes: Truth (is this grounded in reality), Coherence (is this internally consistent), and Intent (is this what was actually wanted). They’re orthogonal, which is why a spec can pass grounding and still be the wrong thing.

• Grounding the spec. The blocking gate above, in full: evidence-or-it-doesn’t-count, the leak-rate metric, and layer confusion as the real enemy.

• Contracts, Not Tasks. How you hand work to an agent matters more than which agent, and the principle underneath: decomposition granularity should scale inversely with the strength of your acceptance gate.

There’s more behind these: why the whole thing compounds over time, what to do about the one axis no machine can check, and the honest numbers from measuring my own pipeline. The series will get to it. But it starts with the reframe, because it reorganizes everything else: the implementation was never the hard part. Stating the truth precisely enough to compile it — that’s the job now. Build the compiler for that.

Next: The Oracle Lens — the three kinds of truth a gate can check, and the one it can’t.