PRDs in Agile: Spec Without Waterfall

The objection to specs in agile teams is fair and worth taking seriously: a document written up front, approved, and then treated as fixed is the thing agile was reacting against.

But notice what usually replaces it. Not a lighter process — nothing. The decisions still get made; they just get made verbally, mid-sprint, by whoever hits them, and nobody writes them down. That is not agile. It is undocumented, which is a different property that happens to feel similar from the inside.

What the manifesto actually says

Working software over comprehensive documentation.

Over, not instead of. And the line directly beneath the four values, which gets quoted far less often, says that while there is value in the items on the right, the items on the left are valued more.

That is a statement about priority under conflict. It is not an argument that writing down what you decided is waste, and it never was.

What makes a document waterfall

Not its existence. Four properties, and a document can have none of them:

It is signed off and frozen. Approval converts the document into a commitment, and changing it becomes a political act rather than an ordinary one.

It specifies months at once. The further out it reaches, the more of it is prediction, and predictions age badly.

It is written by somebody who will not be there. Hand-off across an organisational boundary is what makes a spec a contract — nobody is available to answer questions, so the document has to try to answer all of them in advance.

Changing it requires re-approval. This is the load-bearing one. When amendment is expensive, teams stop amending and the document silently stops describing the product.

Notice that none of these is writing things down. They are all ceremony around the document. Strip the ceremony and you keep the artifact.

Four properties that make a spec work in any cadence

Sized to the increment. One or two pages covering the next slice of work, not the whole initiative. The Lean PRD shape exists for exactly this.

Decisions, not predictions. Write what you have decided — the limit, the states, the boundary. Do not write what you expect to be true in Q3. A spec full of decisions ages far better than one full of forecasts, because decisions were accurate at the time by definition.

Amendable with a visible trail. When something changes, append three lines: what changed, what was traded for it, who agreed. That is versioning the decision rather than the document, and it is what keeps a spec honest without a change-control process.

Written to be consulted. During a sprint nobody reads; they look things up. Tables over paragraphs, one rule per sentence, states attached to the requirement they belong to.

A document with those four properties does not slow an iteration down. It removes the twenty minutes each time somebody has to reconstruct what was decided about empty states.

The user story confusion

The most common substitution is the user story, and the reason it does not close the gap is in the format's own design.

As a workspace owner, I want to limit who can invite members, so that I control costs.

That is a good story. It is also, deliberately, a placeholder for a conversation — Ron Jeffries' formulation was card, conversation, confirmation, and the card was explicitly not the specification.

Which works, right up until you notice where the decisions live. The limit. Whether the owner can delegate. What an invited-but-not-accepted member counts as. What happens at the cap. All of that gets settled in the conversation, and the story format has nowhere to put it.

So the confirmation — the acceptance criteria — ends up carrying the whole weight, usually written in a ticket comment, usually after the conversation, usually by one person from memory.

Stories and specs are not competitors. A story says who wants what and why. A spec says what must be true for it to be correct. Teams that run stories with no written decisions are not travelling lighter; they are making the same decisions with no record of having made them.

Where it sits in the cadence

Practically, for a two-week rhythm:

• One increment ahead. The spec for the next slice gets written while the current one is being built. Far enough ahead that refinement has something concrete to attack; close enough that the context has not moved.
• Refinement is the review. This is where the spec gets pressure-tested — not a separate ceremony, just the session you already hold, with a document in it worth attacking.
• Amendments land in the document, same day. During the sprint, when a decision gets made in conversation, three lines go back into the spec before the conversation ends.
• Nothing is frozen. There is no sign-off step to reverse.

That is a spec practice with no waterfall in it, and it costs roughly an hour a sprint.

The honest trade

Writing costs time you could spend building. That is real, and any post claiming otherwise is selling something.

The trade is that the time is spent before the work rather than during it. An hour writing the states costs an hour. The same decisions made mid-sprint cost a context switch each, land without review, and leave no record for the person who asks in March.

Sometimes the first hour is genuinely the wrong trade — for a chore, a bug, or a change with no decisions in it, writing a spec is waste. The skill is telling those apart, and that judgment has nothing to do with which methodology you use.

FAQ

Do agile teams write PRDs? Many do, smaller. The manifesto values working software over documentation — over, not instead of.

What makes a spec waterfall? Frozen sign-off, months of scope, an absent author, and amendment requiring re-approval. All ceremony, not the document.

Do stories replace specs? No. A story is a placeholder for a conversation, and the conversation is where the decisions are made.

How far ahead? About one increment — concrete enough to interrogate, close enough that context has not moved.