What a Specification Has to Contain Now

What a Specification Has to Contain Now is a different document from the ticket it replaces, because a ticket was written for somebody who would ask a question before starting. An agent does not ask. It resolves every ambiguity itself, immediately, and usually in a way that looks reasonable in the diff.

Key takeaways

• A specification for an agent states observable behaviour, scope boundaries and acceptance conditions, and deliberately leaves implementation choices open. Those are four different sections, not one paragraph.
• SWE-bench Verified is a human-filtered subset of 500 instances where annotators checked that problem descriptions were clear, test patches correct, and tasks solvable given the available information. Underspecification was common enough to need filtering.
• GitHub's spec-driven development names four phases, specify, plan, tasks and implement, and describes the spec as a contract for how code should behave and the source of truth tools and agents use.
• Requirement phrasing is a solved problem with a 2009 primary. EARS gives six sentence patterns keyed on shall, when, if, while, where and upon, and each one removes a specific class of ambiguity.
• DORA's 2025 report found that 56% of respondents rely on AI for creating specifications. The document the agent works from is increasingly written by an agent, which makes the human review of the spec the load-bearing review.

Read this beside Chapter 3, which covers the standing context every agent inherits before it reads a task, and Chapter 4, which turns the acceptance conditions here into an executable contract. Chapter 7 sets the size limit that the scope section has to respect.

The ticket says: add rate limiting to the public API. A senior engineer reads that and walks over to ask three questions before touching anything.

Per key or per address. Reject at the limit or queue and slow down. Which endpoints, and what happens to the health check.

An agent implements it in eleven minutes. It picks per address, rejects with a 429, applies the limit to every route including the health check, and writes a clean, tested, idiomatic module. The review will be about the wrong things for two days.

Underspecification is the normal case, not the exception

There is a useful piece of public evidence that vague problem statements are the default rather than an occasional lapse. SWE-bench Verified exists because of it.

The benchmark's own description is precise about what was done. It is a human-filtered subset of 500 instances from SWE-bench, created in collaboration with OpenAI, where human annotators reviewed each instance to ensure the problem descriptions are clear, the test patches are correct, and the tasks are solvable given the available information.

Sit with the implication. A research benchmark built from real issues in real repositories needed a human filtering pass before it could fairly measure whether a model solved the task, because a large share of real issues did not state their problem clearly enough to be solvable. That is your backlog too.

The instinct is to blame ticket authors. I would not. Tickets were always a prompt for a conversation, and the conversation was doing the specifying.

A specification, defined against the ticket it replaces

A specification, for this purpose, is a written statement of the observable behaviour a change must produce, the boundary of what it may touch, the conditions under which it will be accepted, and an explicit note of the decisions left to the implementer.

Four parts, and the fourth is the one nobody writes. Naming what is deliberately open prevents an agent from treating every open question as a decision it should quietly make and prevents a reviewer from arguing about a choice that was never constrained.

What a specification is not is a design document. It does not name classes, it does not choose a library, and it does not describe the shape of the code. The moment it does, you have spent the expensive human hour on the cheap half of the work.

DORA's State of AI-assisted Software Development 2025, published 24 September 2025 from 4,867 respondents, reports that 56% rely on AI for creating specifications and 49% for analysing requirements. So the spec is increasingly drafted by an agent as well. That is fine, and it moves the load-bearing human review one step earlier, onto the spec itself.

The four phases GitHub names, and what each one buys

GitHub's spec-driven development post of 2 September 2025 describes the spec as a contract for how your code should behave, and as the source of truth your tools and AI agents use to generate, test and validate code. Its toolkit, Spec Kit, whose documentation page was last updated 16 July 2026, names four phases: specify, plan, tasks, implement.

The value is not the tool. It is that each phase produces a separate written artifact, which gives you four cheap places to disagree instead of one expensive one.

Specify holds intent and acceptance. Plan holds the technical approach, the constraints and the stack decisions, which is where an architect intervenes. Tasks breaks the plan into what GitHub describes as small, reviewable chunks that each solve a specific piece of the puzzle. Implement is the only phase that produces code.

Spec Kit's own framing of why this helps is worth borrowing: the artifacts give the agent structured context instead of ad-hoc prompts. That sentence is the whole argument for writing any of it down.

The failure mode to watch for is a plan phase that becomes a design review by another name. Keep it to constraints and the decisions that would be expensive to reverse.

Success criteria, not implementation detail

The single most useful editing rule for a specification is to ask, of every sentence, whether it describes something an outsider could observe.

A statement about behaviour survives that test. Requests above the configured rate receive a 429 with a Retry-After header. A statement about structure does not. Use a token bucket in a middleware class.

The reason to be strict is not purity. It is that behavioural statements are testable and structural ones are not, and Chapter 4 turns every acceptance condition into a test. A requirement you cannot express as a check is a requirement the agent is not actually held to.

There is one legitimate exception and it should be labelled as such. Where a structural constraint genuinely matters, because of an existing pattern, a licence, or an operational limit, state it as a constraint in the plan rather than smuggling it into the behaviour.

Phrasing a requirement so it cannot be read two ways

This part has a 2009 primary, and its age is the point: nothing about agents changed it. Mavin, Wilkinson, Harwood and Novak presented the Easy Approach to Requirements Syntax at the IEEE Requirements Engineering conference in 2009, developed while analysing airworthiness regulations for a jet engine control system, and it addresses eight named requirement problems including ambiguity, vagueness and testability.

EARS is six sentence patterns. Ubiquitous behaviour reads the system shall do something. Event-driven reads when a trigger occurs, the system shall respond. Unwanted behaviour reads if a condition holds, then the system shall respond. State-driven reads while in a state, the system shall behave a certain way. An optional feature reads where the feature is present, the system shall do something. And complex behaviour combines an event with a condition.

Six patterns is a small enough set to hold in your head. The discipline they impose is that every requirement declares which kind it is, which forces the author to notice when they have not decided whether a rule is a trigger or a state.

I use them for one narrow reason. Unwanted behaviour, the if-then pattern, is the class agents get wrong most often, because a specification that never states what happens on failure gets a failure path invented for it.

Scope sized to one deployable unit

A specification also has to bound size, and there is a good public formulation of the bound. Faros AI, which sells engineering-productivity analytics, recommends that the plan phase produce a scope resulting in a pull request that can be deployed to production as a distinct, self-contained unit of value, and that can pass the full pipeline independently.

That is a better rule than a line count, because it is checkable before any code exists. Ask two questions of the spec. Could this ship on its own. Could it be reverted on its own.

If either answer is no, the specification covers more than one change and should be split now, while splitting is a paragraph edit. Chapter 7 covers what happens when it is not split, and the short version is that the review queue absorbs the cost.

The same requirement written three ways

The table below is the compact form of the editing pass, and it is the artifact worth pinning above a backlog grooming session.

The third row is roughly forty words longer than the first. Forty words is cheaper than two days of review.

A worked example, composited and labelled

The details here are composited from ordinary production shapes rather than one system, and the shape is exact.

A team specifies a bulk export feature as: let admins export their organisation's records to CSV. The agent produces a working endpoint that loads every record into memory and returns them synchronously. It is correct against the sentence written.

It falls over on the fourth-largest customer. The review had approved it, because the diff was clean and the tests passed the tests the agent also wrote.

The respecified version adds three lines. Exports shall complete for organisations up to five million records. While an export is running, the requesting admin shall see progress and be able to cancel. If the export exceeds ten minutes, the service shall deliver it asynchronously by link rather than in the response.

None of those three lines mentions a queue, a worker or a storage bucket. All three are observable, all three are testable, and together they make the memory-loading implementation impossible to pass off.

The objection: this is waterfall wearing a new hat

The objection is fair on its face, and I would put it more sharply than most people do: detailed up-front specification failed for thirty years, and calling it a spec phase does not fix it.

Three things differ, and they are structural rather than rhetorical. The unit is one deployable change rather than a release, so the specification is a page and not a binder. The feedback loop is minutes, so a wrong specification is discovered in the same sitting rather than a quarter later. And the artifact is revised in place rather than change-controlled, because the cost of rewriting it is now trivial.

What has genuinely not changed is the danger. A team that writes a fifteen-page specification for a two-day change has recreated the failure exactly, and the tell is a specification that describes structure rather than behaviour.

The honest cost is real, and it is the reason this chapter comes second rather than last. Specification work is senior work, and it moves effort from the end of the process to the beginning. The trade is that you spend it once, on a document, rather than repeatedly, in a review queue whose median waiting time Chapter 1 already showed rising.

Chapter summary

A specification an agent can implement contains four parts: the observable behaviour the change must produce, the boundary of what it may touch, the conditions of acceptance, and an explicit note of what is deliberately left open, with that fourth part being the one almost nobody writes and the one that stops an agent quietly deciding things nobody constrained. Underspecification is the ordinary case rather than a lapse, which is why SWE-bench Verified is a human-filtered subset of 500 instances where annotators checked that problem descriptions were clear, test patches correct and tasks solvable given the available information. GitHub's spec-driven development post of 2 September 2025 describes the spec as a contract for how code should behave and the source of truth tools and agents use, and Spec Kit's four phases, specify, plan, tasks and implement, are useful mainly because each leaves a separate written artifact that can be argued with cheaply. Every sentence should describe something an outsider could observe, since behavioural statements are testable and structural ones are not, with genuine structural constraints stated as constraints in the plan rather than smuggled into behaviour. Phrasing is a solved problem with a 2009 primary: EARS gives six patterns keyed on shall, when, if, while, where and upon, and the if-then unwanted-behaviour pattern is the one whose absence causes the most damage, because an unspecified failure path gets invented. Scope is bounded by asking whether the change could ship alone and be reverted alone. And DORA's 2025 finding that 56% of respondents use AI to create specifications means the human review of the spec is now the load-bearing review.

A specification covers one task. It cannot carry the conventions, architecture and secure coding standards that apply to every task, and repeating them per ticket is how they rot. Chapter 3 is The Standards Every Agent Inherits, which is the layer underneath this one.