# Specification Standard

> The difference between a story and a specification, the sections a spec needs, and the five-question test that tells you whether an agent can build from it without guessing.

Source: https://www.koombea.com/ai-pods/standards/specification/

---

## 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 {#core-sections}

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 {#context-sections}

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 {#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 {#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.

1. Is there any requirement the agent would have to look up elsewhere to understand?
2. Is there any behavior that is implied but not stated?
3. Could two reasonable people read this and build different things?
4. Are the cases where something should not happen as explicit as the cases where it should?
5. 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](https://www.koombea.com/ai-pods/standards/validation/).

## 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.