DOCS · START HERE
Why spec-driven delivery
The case for approving a specification instead of reviewing a diff — what it costs, what it buys, and where it does not pay off.
On this page
The expensive defects in AI-assisted delivery are not syntax errors. They are misunderstandings, shipped confidently. A spec is where a misunderstanding is cheapest to find.
Where the cost actually lands
The cost of a wrong assumption is roughly the amount of work built on top of it before anyone notices. Coding agents raised the amount of work that can sit on top of an assumption before a human looks — that is what "10× faster" means in practice. The correction cost went up with it.
| Caught at | What you are reading | What it costs to fix |
|---|---|---|
| The spec | A paragraph and a list of criteria | A comment and one edit |
| Code review | 600 lines that all look plausible | A rewrite, plus the review time already spent |
| QA | A behaviour that is wrong but works | A rewrite, a re-test, and a schedule slip |
| Production | An incident | All of the above, plus the incident |
Reviewing a spec is not extra work added to reviewing a diff. It is the same review, moved to where it is cheap — and it is a review a non-author can actually do, because a spec is written in the language of the problem rather than the language of the solution.
Why "just write better prompts" does not hold
- A prompt is not durable
- The context you assembled by hand is gone at the end of the session. The next ticket starts from zero, and so does the next engineer.
- A prompt is not reviewable
- Nobody reviews a prompt. There is no artifact with a name on it, so there is nothing to disagree with before the code exists.
- A prompt is not accountable
- When a generated change turns out to be wrong, "the AI wrote it" is not an answer an organisation can use. A spec with an approver is.
The review a team can actually sustain is the one that reads a page, not the one that reads a diff nobody has time for.
Why the knowledge base is the other half
A gate without grounding just slows you down: a human approving specs that were invented from nothing is a human doing the agent's research for it. The knowledge base is what makes the spec cheap to produce and cheap to check.
- It is written in your repository, as markdown, in the same pull request as the code it describes — so it cannot silently fall behind.
- It is retrieved, not recited: the agent pulls the passages that answer this ticket, and cites them by a string a reviewer can look up.
- It compounds: the last task of every spec files the as-built record back into
knowledge/specs/, so the twentieth spec is written against nineteen delivered ones.
What it costs
Be honest with your team about the price, because it is real and it lands in a specific place.
- A review step that did not exist before
- Someone has to read and approve the spec. In practice this is minutes, not hours — the spec is a page, and the citations are what make it skimmable. But it is a new named responsibility, and if nobody owns it the queue stalls.
- A one-time grounding pass
- Onboarding drafts the knowledge base by reading the repo, and someone has to review that pull request properly. Skimming it defeats the point: everything downstream cites it.
- Discipline about
UNVERIFIED - An unanswered question is only useful if somebody eventually answers it. A team that learns to ignore the marker has re-created the wiki nobody trusts.
Where it does not pay off
- A typo fix, a dependency bump, a copy change. There is no misunderstanding to catch, so the spec is pure overhead — do it the normal way.
- Genuine exploration, where the point is to find out what the problem is. Spec the thing you learned, not the learning.
- A codebase nobody intends to keep. Grounding a repository you are about to delete is work you will not get back.
specd does not force itself into those paths — it is a lane for the changes that carry risk, not a replacement for your entire git workflow.
How you would know it worked
The claim "the AI helps" should be a number you can check. These are the ones worth watching, and specd instruments the pipeline it installs so they come from your own delivery rather than from a vendor slide.
| Signal | What a healthy number looks like | What a bad one is telling you |
|---|---|---|
| Ticket → approved spec, median | Days, trending down as the knowledge base fills in | Weeks — the specs are not answerable from your docs yet |
| First-pass PR acceptance | Rising: the spec caught what review used to | Flat — the spec is being approved without being read |
| Citations per spec | Rising with knowledge-base coverage | Near zero — retrieval is not finding your docs |
UNVERIFIED claims per spec | Falling as open questions get answered | Rising — the docs are drifting from the code |