Spec-driven development has a clarify step and no way to run it

In June, Microsoft published its case for spec-driven development: stop prompting first and aligning later, write a structured spec, and let AI execute against it. The spec becomes "the connective tissue across the lifecycle."

The argument is sound and the timing is obvious — every major AI coding tool has now shipped some version of this. What makes the post worth reading closely is not the pitch. It is step three.

The lifecycle

GitHub Spec Kit, the open-source toolkit Microsoft built for this, defines seven steps:

1. Constitution — principles, standards, guardrails
2. Specify — requirements, scenarios, acceptance criteria
3. Clarify — resolve ambiguity, dependencies, and edge cases
4. Plan — architecture, flows, constraints
5. Tasks — implementation-ready units
6. Implement — generate code and tests
7. Validate — verify output matches the spec

Six of those seven are things a tool can do well. Constitution is configuration. Specify is a template. Plan, Tasks and Implement are what coding agents are already good at. Validate is tests.

Clarify is a judgment call about your product, and it sits in the middle of the workflow as the step everything downstream depends on.

Microsoft says the quiet part

Two lines in the post do more work than the rest of it.

The first is a limit, stated plainly:

AI can accelerate those steps, but it cannot correct ambiguity that was never resolved.

The second is the summary of what they learned running this across teams:

Spec quality = output quality.

Read together, those are not a product claim. They are a conditional. Spec-driven development improves your output if your spec is good, and the post is explicit that the tooling does not make it good — it makes it structured, which is a different property. A well-formatted spec with an unresolved ambiguity in it is still an unresolved ambiguity, now in a machine-readable wrapper and travelling faster.

Why clarify is the hard step

There is recent evidence about exactly this, and it is not encouraging.

An April 2026 benchmark called Orchid tested five models on 1,304 function-level Python tasks with injected ambiguity. Asked directly to find ambiguity in a requirement, the models showed some ability to recognise that it was present — but the authors report they "suffer from overprediction" and "consistently fail to precisely localize the source of ambiguity or provide valid resolutions." The paper frames it as a gap between detecting a problem and understanding its logic.

That is the Clarify step, benchmarked. Detection is partial and noisy. Localisation and resolution are not working yet.

Which means the one step in the lifecycle that cannot be delegated to the same class of system is the one the other six are standing on.

What the case studies do and do not show

Microsoft's post includes three examples, and they are worth reading with the right expectations.

In one brownfield project, capturing a repeated onboarding pattern in parameterized specs took onboarding a new asset type from 2–3 weeks to a few days. Another aligned PMs, architects and engineers on a globally distributed platform. A third moved a React prototype to a working product with multiple agents.

These are self-reported case studies from the vendor, with no control, no sample size and no stated methodology. That is not a criticism — a practitioner blog post is not a trial, and it does not pretend to be one. But it means the 2–3 weeks to a few days figure describes one team's experience, not a measured effect size, and it should not be quoted as though it were.

The mechanism is plausible. The magnitude is unestablished.

What this changes about how you spec

The practical shift is narrower than the framing suggests, and more demanding.

The spec became load-bearing. It always mattered; now it is the input to a generator that will not push back. Microsoft's own framing — it cannot correct ambiguity that was never resolved — is the whole reason the review step moves earlier.

Structure is not clarity, and the tooling supplies structure. A spec that passes a template check can still contain "handle appropriately," "recent items," and a metric with no baseline. Nothing in a seven-step lifecycle catches those; a person reading adversarially does.

The clarify step needs an owner and a method. It is listed as a phase, not a technique. Whether your team runs it as a checklist, an adversarial review, a second reader, or a tool, it has to be something more specific than a heading — because it is the only step where the quality of the whole run is decided.

Right-sizing is in the guidance. Microsoft says plainly that "not every change needs the full lifecycle." That is the most reusable sentence in the post and the one most likely to be ignored by teams adopting the process wholesale.

The honest summary

Spec-driven development is a real shift and the direction is correct: if agents are writing the code, the specification is where the remaining human judgment lives.

But the industry has spent a year building tooling for six of the seven steps and the seventh is the bottleneck. Every framework has a clarify phase. None of them, on current evidence, can actually perform it — and the model you would ask to do it is the same one that will confidently implement whichever reading it happened to pick.

The step is named. The method is still yours to bring.

FAQ

What is spec-driven development? A spec-first workflow where a structured specification is the source of truth for both people and AI agents generating code against it.

What are the Spec Kit steps? Constitution, Specify, Clarify, Plan, Tasks, Implement, Validate.

Does it improve output? Microsoft's own summary is "spec quality = output quality" — a conditional. The published case studies are self-reported and uncontrolled.

Why is clarify hard to automate? Detecting ambiguity and locating it are different tasks. An April 2026 benchmark found models partial at the first and consistently failing at the second.