A story tells you the direction.
A specification tells you exactly where you are going, what is out of bounds, and what to do when things do not go as expected. That difference now decides delivery speed.
A story is not a specification
Two kinds of work item arrive on a board. A user story describes what someone wants and why. A technical story describes work whose beneficiary is the system rather than a person: a migration, a performance threshold, a schema change.
Both need a spec, and the structure is the same. What differs is the language of the acceptance criteria.
Either way, the story captures requirements. It is a starting point. A specification takes those requirements and resolves every ambiguity before work begins.
That is the whole distinction, and it is not about section count. A story leaves room for interpretation, and a senior developer fills that room with experience, conversation, and judgment. An agent fills it with a guess. Every gap in the spec becomes a guess in the output.
A specification answers every question an implementer would need to build it correctly the first time:
- What does done look like?
- What happens at the boundaries?
- What is explicitly not included?
- How will we know it is correct?
- What does it connect to?
The sections a spec needs
Five core sections are always required. For user stories they are written at the business level, client-readable. For technical stories they describe system-level outcomes in plain language, specific and measurable.
| Core section | What it contains | Why it is required |
|---|---|---|
| Goal | One sentence: what this achieves and for whom | Anchors every downstream decision. Without it an agent optimizes for the wrong outcome |
| Audience | Who this is for | Shapes scope, language and format |
| Acceptance criteria | Numbered, testable statements of done | The agent's definition of done. Each one maps to at least one test |
| Out of scope | Explicit exclusions | Prevents over-building. Ambiguity about scope becomes extra features |
| Definition of done | An explicit checklist | The agent knows when to stop |
Context sections, added when relevant
These give the implementing agent the reference material it needs without crowding the core sections. They do not change what the product must do. They define how it connects to everything around it.
| Context section | When to include it |
|---|---|
| Design reference | Any work with a visual component. Link the specific frame or node, not the file. Without it the agent reads the wrong frame or guesses |
| User flow | Multi-step journeys where the criteria alone do not convey the sequence. Skip it for a single action |
| Technical contracts | Whenever the work must satisfy an external interface or constraint. An API specification, a schema, a payload format, a performance threshold. If the contract does not exist yet, implementation is blocked until it does |
| Problem | Technical stories where the goal alone does not make clear what exists today and what must change |
| Dependencies | When the work cannot start until another item, endpoint or system is ready |
| Data sources | Reports, dashboards, and anything consuming external data |
On fragmentation. Spec information tends to scatter across a tracker, a repository, design files, and a test tool. Each holds a piece and none holds the whole. An agent starts from the work item. If the information is not there or linked from there, the agent does not have it, and fills the gap with its best guess rather than yours.
Writing acceptance criteria
Criteria for user stories are business-level. They describe what a person can do and what they experience, not how the system implements it.
| Write this | Not this |
|---|---|
| The user can sort the hotel list to show the cheapest options first | Sort returns hotels in ascending order when sort_by=price_asc is passed to the API |
| Sharing a trip via link lets guests without an account view it | The share token is appended to the URL and validated server-side against a 24-hour expiry |
The technical detail is not wrong. It is in the wrong section. Endpoints, parameters and expiry logic belong in the technical contract.
Criteria for technical stories are system-level, and still specific and testable.
| Write this | Not this |
|---|---|
| The hotel list endpoint responds in under 200ms for payloads up to 100 items under normal load | Performance should be acceptable |
| The schema migration completes without data loss on a dataset equivalent to production volume | The migration should work correctly |
Three tiers, and which work needs which
Tiers describe how much ambiguity remains, not which sections exist. They are floors, not targets.
| Tier | What it has | Who can build from it |
|---|---|---|
| Human-workable | Title, description, rough criteria | A senior developer who knows the codebase and can ask questions. Not an agent, and not a developer new to the code |
| Agent-assistable | Complete core sections, structured criteria | An agent with human oversight and review |
| AI-ready | All of the above plus edge cases, exclusions, definition of done, and every relevant context section | An agent running with minimal oversight. No ambiguity it would have to resolve alone |
Not every item needs the top tier. Match it to the risk.
| Work type | Minimum tier |
|---|---|
| One-line bug fix, copy change | Human-workable |
| Simple interface change, minor feature | Agent-assistable |
| New feature, integration, data work | AI-ready |
| Auth, permissions, billing, security | AI-ready, no exceptions |
The cost of writing an AI-ready spec is an hour. The cost of reworking an ambiguous implementation is a sprint.
The completeness test
Before a spec is handed off, five questions. A yes to any one of them is a gap, and the spec goes back.
- Is there any requirement the agent would have to look up elsewhere to understand?
- Is there any behavior that is implied but not stated?
- Could two reasonable people read this and build different things?
- Are the cases where something should not happen as explicit as the cases where it should?
- If the agent hits an edge case, is the expected behavior written down?
A spec that passes is ready. A spec that does not is a guess factory.
Who owns what, and when
Each artifact has one owner and one moment. The specification is authored and owned by product. Design contributes the design reference when the frame is marked ready. Engineering contributes the technical contract before development begins. Nothing is ready for build until every required section is present and every contributor has signed off on theirs.
Quality derives the validation plan from the spec. It is a separate artifact, written from the spec before the build starts rather than after it, and that sequencing is the subject of the validation standard.
Traceability
For the work to be auditable, every feature traces from spec to test. The spec's job is to ensure every acceptance criterion exists before the build starts. The validation plan's job is to map each criterion to a test that proves it. A criterion with no test is not done, and a test with no criterion is not evidence of anything.
Why this is the bottleneck now
Implementation speed used to be the constraint. It is not anymore. An agent produces in hours what took days, which moves the constraint upstream to how well the work was described.
Errors compound in that direction. A mistake in the specification does not produce one wrong behavior. It produces a wrong implementation, wrong tests written against it, and a wrong mental model carried by everyone who touches the work afterward.
- One bad line of code is one bad line
- One bad plan is a hundred bad lines
- One bad spec is a thousand
- Rework at AI speed is still rework
Bring us the backlog.
In 30 minutes, we will show you what a Pod would ship first and how we would price it.