Your PRD and ERD are knowledge, not documents

Every product requirements document I have ever read has the same tragic arc. Weeks of work go into it. It is circulated, commented on, argued over, revised, approved. There is a kickoff meeting where somebody walks through it on a shared screen. And then, within about three weeks, it enters a state of quiet irrelevance from which it never emerges, because the project has learned things the document does not know, and updating a fifty-page document to reflect a decision made in a Thursday standup is nobody’s job.

The knowledge in it does not stop being true. The container stops being consulted.

That distinction is the whole point of this piece. A PRD is not a bad idea. A PRD is a good collection of knowledge in a container designed for a purpose it stops serving almost immediately: persuading a group of people, once, at a moment in time.

Documents are an argument, not a store

It is worth being precise about what a document is optimised for, because it explains the failure exactly.

A document has an order. It has a narrative. It builds context in the early sections that later sections depend on. It has an intended audience and an intended occasion. All of that is machinery for persuasion: you are walking a reader from where they are to where you want them, once.

Knowledge has none of those properties. Knowledge is accessed randomly, by readers who need one part and not the rest, at unpredictable times, often years later, frequently by someone with no idea the document ever existed.

Put durable knowledge inside a persuasion container and three things happen. It becomes unfindable, because it is at position eleven of a document titled after a project that was renamed. It becomes unupdatable, because changing one fact means opening a document that has an approval history and a narrative flow. And it becomes untrustworthy, because a reader cannot tell which parts of a document written in March are still current in November, and the document makes no distinction between the parts that were decisions and the parts that were guesses.

Decompose the PRD, keep the PRD

I am not arguing against writing PRDs. The act of writing one is valuable and the artefact has a real job: getting a group of people to agree, at a moment, on what is being built and why. Do that.

The argument is about what happens afterwards. When the PRD is approved, most of its content is one of four things, and only one of them belongs in a document.

Durable definitions. What a “seat” is in the new pricing model. What counts as an active workspace. These are concepts. They will be referenced by engineers, agents, analysts and support for years, and they will be referenced by people who never read the PRD.

Durable behavioural rules. What happens when a seat is removed mid-cycle. These belong as behavioural concepts, per the previous piece in this series.

Decisions with reasons. We chose per-seat over usage-based, because of these three considerations, and we would revisit it if that assumption changed. This is the highest-value content in most PRDs and the most reliably lost. It deserves its own concept file, and it deserves to be marked as a decision so a reader knows it is history that shaped the present rather than an instruction.

Everything else. Timelines, market framing, stakeholder positioning, the competitive slide, the rollout phases. Genuinely valuable in the moment, genuinely not durable, and correctly left in the document.

The move is not “replace the PRD with a folder.” It is: after approval, promote the durable content out of the document, leave the persuasion in it, and let the document age gracefully into what it always was, a record of a decision made at a point in time.

The ERD case is even clearer

Entity relationship diagrams make the point more sharply, because the drift is measurable.

An ERD is a picture of a schema at a moment. The schema is in the database, and it changes with every migration, and the picture does not, because the picture is in a diagramming tool that nothing is connected to. Within a quarter the diagram is wrong in three places. Within a year it is a museum piece that new engineers are given during onboarding, which is roughly the worst possible use of a wrong diagram.

Here the decomposition is obvious. One file per table. The columns and types are derivable from the schema itself and should be, because that is inventory and hand-maintained inventory is wrong inventory. What is not derivable, and what makes the file worth having, is the part that a schema dump can never tell you.

tables/subscription-events.md
Derivable from the schema (generate it):
columns, types, indexes, foreign keys
Not derivable (this is why the file exists):
customer_id is actually the account id, historical
rows before 2024-03 use the old status vocabulary
written by the billing worker only, never by the API
soft deletes are not used here, unlike everywhere else

That bottom block is the knowledge. It is what an agent needs before writing a query against this table, and it is exactly what is missing when the agent produces something syntactically perfect and semantically wrong. None of it fits in an ERD, because an ERD is a diagram of structure and this is a set of statements about meaning and history.

What this does to the planning phase

There is a second-order effect worth naming, because it changes how planning feels.

When durable knowledge lives in a knowledge base rather than in documents, the next PRD starts differently. Instead of a blank page and a template, the author starts from the existing concepts: here is what a seat currently is, here is what we decided about billing cycles two years ago and why, here is the behavioural rule for mid-cycle changes. The planning work becomes an amendment to a body of knowledge rather than a fresh act of invention.

That is a real productivity difference, but the bigger effect is on quality. Most bad requirements are not bad because somebody was careless. They are bad because the author did not know something the organisation already knew. Every PRD written from a blank page re-litigates decisions that were settled, contradicts rules nobody remembered, and invents a fifth definition of active user.

An agent drafting a plan has the same problem, considerably worse, because it has less institutional memory than a new hire and more confidence than a founder. If it can read the concept files, it drafts against what is true. If it cannot, it drafts against what is plausible. That gap is the difference between an agent that accelerates planning and one that manufactures rework.

Where this breaks down

Decomposition is work, and it lands at the worst moment. The point at which the PRD is approved is the point at which everybody wants to start building. Asking for a promotion pass, where somebody extracts the durable claims into concept files, is asking for unglamorous work at the moment of maximum impatience. In practice it gets skipped unless it is small, and it is only small if you promote a handful of things rather than trying to decompose the entire document.

Some knowledge genuinely needs narrative. The reason a strategy is what it is often cannot be stated as a set of independent concepts. It is an argument, with a shape, where the parts only make sense together. Force that into one-concept-per-file and you get a set of assertions stripped of the reasoning that makes them defensible, which is a real loss and one this format handles badly. Keep the narrative document, and link to it.

Two homes for the same content is worse than one. If the PRD keeps the definition and the concept file also has it, they diverge, and the PRD is the one people will find first because it is the thing with a name everybody remembers. Either the document links out or you have made things worse.

The stale-knowledge problem is amplified for planning artefacts. A decision file that says we chose per-seat pricing, written two years ago, sitting in a directory with no indication that the decision was reversed last spring, is a landmine. Documents at least carry a date and a project name that signals age. A concept file presents as current by default. If you promote decisions into a knowledge base, you need a way to mark supersession, and v0.1 of the format does not define one, so that is a convention you invent and enforce.

And the whole approach assumes somebody owns the directory. A knowledge base assembled from planning artefacts, with no ongoing owner, becomes an archive of what people intended to build in various past quarters. That is not useless, but it is not a source of truth, and the difference matters most to the reader least equipped to tell: an agent, which will treat all of it as current.

The takeaway

PRDs and ERDs are containers optimised for a single act of persuasion, carrying a payload of facts that need to survive for years. The container does its job and then dies, and the payload dies with it, which is why every organisation re-learns its own definitions every eighteen months.

Write the document. Then promote the durable parts (definitions, behavioural rules, decisions with reasons) into concepts with paths, derive the inventory rather than hand-maintaining it, and let the document age into history without pretending it is current.

The next piece looks at the category of knowledge where this pays off fastest and fails most visibly: runbooks, metric definitions, and the shared vocabulary problem that makes two teams in the same company mean different things by the same word.