Specification Engineering and the 80% Problem

Intent engineering closed on a deliberate gap. You can encode what the organisation wants — the trade-off hierarchies, the decision boundaries, the values behind the goals — and still have said nothing about the piece of work in front of the agent this morning. Wanting the right things is a direction, not a destination. The agent also needs to know, in terms an independent observer could check, what finished means for this task, in this repository, this week. That knowledge is a written artefact, the artefact has a discipline, and the discipline is the one I rate above everything else in the stack: specification engineering.

The document that outlives the conversation

Specification engineering tells agents what done looks like. It is the practice of writing documents that autonomous agents can execute against over extended time horizons without a human in the loop — and that phrase, extended time horizons, is what makes it different in kind from the disciplines beneath it, not just in degree. A prompt is an instruction for the next step. A context file is knowledge for every step. An intent framework is judgement for the steps nobody predicted. A specification is none of these. It is a complete, structured, internally consistent description of five things: what the output should be, how its quality will be measured, what constraints apply, which trade-offs are acceptable, and what completion actually means.

Five things, and in my experience the last two are the ones almost every failed delegation skipped. Most task hand-offs describe the output and stop, leaving quality, constraints, trade-offs and completion to be inferred — which is to say, guessed.

The analogy I keep reaching for is older than this industry. When you are building something small, verbal instructions work: “put the shelf about there”. When you are building something large enough to span multiple sessions and multiple builders, you need blueprints — drawings that any competent builder can pick up cold and continue from, because the intent is in the document rather than in anyone's head. The shift from prompt to specification is exactly that transition. And it is not a theoretical one: multi-session autonomous work scaffolded by a structured plan is the pattern Anthropic documented for long-running agents. When an agent runs for hours, or across days of sessions, the specification is what keeps successive sessions producing one coherent artefact instead of several agents' worth of divergent guesses.

The 80% problem, read properly

The name most often attached to why this discipline matters is Addy Osmani's, and his argument is routinely misquoted, so it is worth getting right. Osmani has written two distinct pieces on this theme, and they are not the same claim wearing different numbers. In December 2024 he published “The 70% Problem” — hard truths about AI-assisted coding, from the era when the tools were assistants you supervised keystroke by keystroke. In January 2026 he returned with “The 80% Problem in Agentic Coding”, written for the era this series has been describing, and the second post is not an update of the percentage. It is a different thesis.

The lazy reading — the one I hear in most conversations that cite it — is "agents get you 80% of the way, humans polish the last 20%". Osmani says something sharper: the last 20% changed its nature. It shifted away from typing and towards verification; away from implementation and towards architectural oversight; and towards what he calls “comprehension debt” — the widening gap between the code a team ships and the code that team actually understands. His own summary of the shift is blunt: “the problems didn't disappear, they shifted. And some got worse.”

That correction matters because the two readings recommend opposite responses. If the last 20% were polish, the remedy would be patience — iterate a little longer and the gap closes. Because the last 20% is verification, oversight and comprehension, the remedy is preparation: the gap closes only if you built the means of closing it before the agent started. The 80% problem is not that agents almost finish the job; it is that the job is now a different job, and the remaining work is precisely the work most teams have no written discipline for.

Almost right, at scale

One survey figure suggests how widely that lands. In the Stack Overflow 2025 Developer Survey, 66% of developers cited “AI solutions that are almost right, but not quite” as their top frustration with AI tools. Two-thirds of an industry, naming the same failure shape.

Almost-right is the expensive kind of wrong. Obviously broken output costs you a retry. Almost-right output costs you a review you did not budget for, conducted against criteria you may never have written down — and reviewing against unwritten criteria means iterating towards your own unstated taste, which is the slowest possible way to discover you never had criteria at all. Read that way, a large share of the frustration the survey records is a specification gap wearing a model's name. You cannot verify output against a definition of done that exists only in your head; you can only feel vaguely dissatisfied with it, one revision at a time.

What a specification actually contains

The five questions turn directly into document structure. Here is a trimmed specification for an invented project — Signalbox, a small service that turns build-pipeline events into notifications — for the task of adding a daily digest:

# Spec: digest notifications for Signalbox

## Output
A daily digest job that groups each subscriber's pipeline events
and sends one summary message in place of individual alerts.

## Quality
A subscriber with forty events receives exactly one digest listing
all forty, grouped by pipeline, ordered by severity then time.
Delivery completes within five minutes of the 07:00 trigger at a
load of ten thousand subscribers. A subscriber with no events
receives nothing.

## Constraints
- MUST NOT change the existing per-event alert path; digest is additive
- MUST use the existing template engine; no new rendering dependency
- PREFER one query per subscriber batch over per-subscriber round trips

## Trade-offs
Completeness beats timeliness - a digest five minutes late and
complete wins over one on time and partial.

## Completion
All three quality statements are verified by automated tests; the
operations runbook documents the new job; the digest ships disabled
by default behind a per-subscriber flag.

Read it slowly, because each section is doing a distinct job. Output states the deliverable without prescribing the implementation. Quality is written so that a stranger could verify it — counts, orderings, timings, and the empty case, none of which require asking me anything. Constraints separate hard walls from preferences, which is what stops a correct solution arriving in a shape nobody wanted. Trade-offs answer the collision question in advance, so the agent never has to guess which value wins. And Completion is the section that makes the document a specification rather than a wish: it names the moment the work is over, in artefacts — tests, runbook, flag — rather than in feelings.

None of this is long. The full version of that spec runs to perhaps a page and a half. The effort is not in the writing; it is in the deciding — and that is rather the point, because every decision the spec does not make is a decision the agent will make for you, silently, at machine speed.

Why this is the highest-leverage discipline

Now line the document up against Osmani's shifted 20% and the leverage becomes mechanical rather than rhetorical.

The shifted work is verification — and acceptance criteria written before the work make verification cheap, because checking output against a written standard is fast where discovering your standard by reviewing is slow. The shifted work is architectural oversight — and a constraints section is oversight performed in advance, the architectural veto exercised once in writing instead of repeatedly in review. The shifted work is comprehension debt — and the specification is the one durable record of intent the codebase gets: months later, when nobody remembers why the digest ships disabled by default, the document says what was meant, not merely what was built.

There is a second, simpler leverage argument. Every layer below this one is an amplifier. A better model, a richer context, a tighter harness — each multiplies whatever you feed in at the top, and what you feed in at the top is the specification. A weak specification, perfectly executed, is a strong failure — delivered faster, at scale, with confidence. That is why I weight this discipline above the rest of the stack: it is the only layer where an hour of work improves everything downstream of it, including work done by agents you have not met yet.

The honest ledger, before the hand-off: a specification does not remove the last 20%. Nothing does. What it changes is who finds that work and when — gaps surface at writing time, when they cost a sentence, rather than at review time, when they cost a rewrite. I still ship specs with holes in them; the difference is that the holes are now findable, because there is a document to hold them up against.

A specification can look monolithic from outside — one more big document to dread writing. It is not. Every spec I write, and every context file and plan beside it, is assembled from the same five small moves. Next, the five primitives — the craft layer underneath every discipline in this series.