The PRD is a working file, not a document

Here's an illustration, made up to show the shape of the problem. A spec for a new export feature says users can export up to a year of history. Two weeks into the build, someone on a call points out that a year of history times the biggest accounts is a very large file, and the team agrees to cap exports at ninety days for now. Everyone nods. The spec still says a year. A month later an agent picks up the follow-up work, reads the spec it was pointed at, and builds the settings screen with a one-year option. It did exactly what the document said.

When someone finally notices, the first question is "when did these split?" Nobody can answer it. The decision is real, but it lives in a call nobody recorded and a chat thread nobody can find. The spec was signed off and then left alone, and the work kept moving without it.

This is an opinion piece about specs, and here's my claim. I think a PRD should be treated as a working file, one that lives next to the work, changes when decisions change, and gets argued with line by line while the thing is built. Not a document that gets approved and filed.

Why a signed-off spec drifts

A spec has a lot of readers right up until it's approved. People comment, push back, ask what a line means. Then it gets signed off, and its readership drops close to zero. The engineers have what they need, or think they do. The product manager moves to the next thing. The document is done.

But the decisions aren't done. They keep happening, because building something is how you find out what you didn't know when you wrote it down. The cap on exports, the edge case nobody thought of, the dependency that turned out to be slower than expected. Each of those changes what the spec should say.

The trouble is where those changes land. They happen in standups, in chat, in a quick call, in a code review comment. They land wherever the conversation happened to be, and the spec isn't usually where the conversation is anymore. So the file that's supposed to describe the thing slowly turns into a description of what someone thought the thing would be, back when it was approved.

I don't have data on how often this happens or how fast. I'm reasoning from how documents get used, and you can check it against the last few specs you've worked from.

Why agents raise the stakes

A person working from a stale spec usually has some idea it's stale. They were on the call. They remember the cap. They read the spec, notice it's out of date, and build the right thing anyway, maybe without even mentioning it.

An agent doesn't have that. It wasn't on the call. It reads the version it was handed, and it reads it literally. If the spec says a year, the agent builds a year, and it does it well, with tests and a tidy description of the change. A stale spec doesn't get quietly corrected along the way. It gets built faithfully.

I think that changes what a spec is for. When the only readers were people who'd been in the room, a spec could be a rough sketch and the gaps got filled in by memory. When some of the readers are agents, the spec is closer to an instruction. Whatever it says is what gets built. The gap between "what we decided" and "what the file says" stops being a documentation problem and becomes a build problem.

What a working file looks like

If the spec is going to keep up, it needs to behave less like a document and more like the code it describes.

It sits next to the work. Not in a separate system that someone has to remember to open, but close enough to the plan or the code that changing one makes you look at the other.

It changes when decisions change. When the team agrees on a ninety-day cap, the line that said a year gets edited, today, by whoever made the call. The file reflects the current decision, not the original one.

Comments sit on the specific line they question. "Does a year really work for big accounts?" belongs on the line about a year, not in a general thread at the bottom or a chat somewhere else. When the question is attached to the line, the answer tends to get written into the line too.

And the agent reads today's version. Not a copy pasted into a prompt three weeks ago, but the file as it is right now, with the decisions that have happened since.

We keep our own plans and briefs as working files that get commented on while they change. It's less tidy than a finished document, and I think it's how the file stays true to the work.

What to stop doing

If you write specs, a few habits are worth dropping.

Signing off and walking away. Approval should be the point where the spec starts getting real use, not the point where it stops getting attention. If you own the spec, you own keeping it current while the thing gets built.

Keeping decisions in meeting notes. A decision written down in the notes from a Tuesday call is effectively hidden from anyone, person or agent, who reads the spec instead. If a call changes what you're building, the spec should change before the call is over, or right after.

Writing a spec nobody will comment on. A spec that reads like a finished essay invites approval, not argument. A spec that's clearly a working draft, with open questions marked as open, invites people to push back on the specific lines that are wrong. You want the pushback. It's how the file stays honest.

None of these are hard. They're just different from treating the spec as a deliverable you hand over.

The spec is where the decision keeps being made

Here's the reframe I'd leave you with. We usually think of a spec as the record of a decision. Something was decided, the spec wrote it down, and now the spec is the evidence.

I think that's backwards for any project where the work teaches you things. The spec isn't the record of a decision that already happened. It's the place where the decision keeps being made, every time someone learns something that changes it. If the decision moves somewhere else, a call or a thread or someone's memory, the spec stops being the place, and whoever reads it next, person or agent, builds the old decision.

So the question isn't whether your spec was right when it was approved. It's whether it's right today, and whether the next reader will find today's version.

Written by the team building Gander, live review for markdown an agent is still writing.