How do you keep an AI PRD from becoming a technical design doc?

How to answer this, stage by stage

Eight moves. Ground it in one sentence you'd actually be tempted to over-write, not a lecture about PRDs in general.

Let's learn

What happens when a document written to say what's broken starts saying how to fix it instead?

Say we build a tool that looks at each store's sales and stock, and tells the ordering system when it's time to reorder a product, so the shelf doesn't sit empty and the produce in back doesn't rot before anyone notices.

Right now, a store manager checks a spreadsheet once a week, during the Friday inventory walk: reorder anything with less than two weeks of average sales left. It's rough, but it mostly holds. About 9 of every 100 fast-selling items still run out before the next delivery, mostly because a week is a long time for anything to speed up between checks.

Now say the PRD for the AI version gets written. In the requirements section, under a heading called Technical Approach, it reads: "Recompute the reorder signal nightly, at 2am, using a 21-day rolling average and a 1.3x safety-stock multiplier. Store the result in a new reorder_signals table." It reads precise. It reads like someone did their homework.

Here's the part that's easy to miss.

That sentence isn't a writing problem. It's already an engineering decision, made by the one person in the room who isn't supposed to be making it, before anyone asked what freshness the signal actually needed to hit.

The section she always fills in herself, before any rule exists

Engineering builds it in three sprint weeks, to the letter. Then a store runs a weekend promotion on a fast-moving item. The promo goes live Saturday morning. The signal doesn't recompute until the Monday 2am run. For the whole weekend, the system is still reading Tuesday's sales.

Here's where it costs the most. Once the stockouts start showing up, engineering points at the PRD. The batch cadence was written down, so from where they sit, it isn't a bug. It's per spec. Fixing it means reopening a requirements document, not just a ticket, and that takes two more sprint weeks on top of the three already spent building the exact thing the PRD asked for.

A technical detail sitting in a requirement isn't neutral. It's a decision, made by accident, to protect one implementation from ever being questioned, because the document that was supposed to describe the problem already answered it.

The choice I would take back. The team's PRD template had an open "Technical Approach" section, and leaving it blank felt like handing over an unfinished document. I would cut that heading from the template entirely, or rename it "Signal Freshness Requirement" and force it to hold a number, not a mechanism.

What I would leave alone. The exact wording on the reorder alert a store manager sees. That's fine to spec down to the word, because there's genuinely one right answer for what a manager needs to read at a glance, and it isn't an implementation choice at all.

The lesson. A requirement that only one technical answer could satisfy isn't a requirement anymore. It's already halfway to being code. If the PRD survives someone building it a completely different way underneath, it was written at the right altitude. If it doesn't, it was a design doc wearing a PRD's cover page.

Now here is the same thing as a story

Read this version when you've got three minutes, not thirty seconds, since a promo weekend makes the point better than any rule does on its own.

The PRD template at Briarcross Grocers has a section called Technical Approach, sitting empty until someone fills it in.

Thandeka Nkosi had filled it in a hundred times before anyone thought to ask whether she should. She'd been the product lead for supply chain tools at the 14-store chain for three years, and before that she'd spent four years as a data analyst. So when a document asked her a technical question, she had an answer sitting right there, and she gave it. Nobody had ever told her not to.

For most of those PRDs, that habit never cost anything. A dashboard. A reorder alert. Small tools, where a stray sentence about how something worked underneath didn't change what got built or whether it worked.

Then came the reorder-point predictor, the tool that would replace the Friday spreadsheet check every store manager did by hand. Thandeka opened the template, got to Technical Approach, and did what she always did. "Recompute the reorder signal nightly, at 2am, using a 21-day rolling average and a 1.3x safety-stock multiplier. Store the result in a new reorder_signals table." Nobody in the doc review flagged it. It read like exactly the kind of precision a PRD is supposed to have.

The swap test, run on the actual sentence Thandeka wrote

Engineering built it in three sprint weeks, to the letter. Calendar-driven nightly job. Rolling average. Safety multiplier. Nothing dramatic. It just worked, on an ordinary Tuesday, the way it was written to.

Nothing announced what came next either. No single question, no single email. It just built up, one Saturday at a time.

The first weekend Briarcross ran a promo on rotisserie chicken, one store's shelf went empty by mid-morning. The manager restocked from the back room and shrugged it off, the kind of thing that happens sometimes. The second weekend, two more stores hit the same wall on a different item. By the sixth weekend, all 14 stores had run dry on a promoted item at least once, and a district manager named Milo Sarkisian finally sent Thandeka a photo of an empty end-cap on a Saturday afternoon, captioned: "thought this was supposed to fix this."

She checked the timestamps. The promo had gone live Saturday at 8am. The signal wouldn't recompute until the Monday 2am run. The whole weekend, the system was reading Tuesday's sales, confident and wrong.

She raised it with engineering. Their answer wasn't wrong, exactly: the batch cadence was in the PRD, so as far as they were concerned, it was working as specified.

Milo wasn't upset with anyone in particular, and neither was Thandeka, once she saw it. Nobody had been careless. She'd written the sentence the same way she'd written a hundred sentences before it, in documents where it never mattered. The problem was never her judgment about batch jobs. It was that a PRD had let her make that judgment at all, in a section that read like a decision instead of a question left open.

The day the batch job was wrong, and what changed when the PRD stopped naming it

So here's what she rewrote, that same week. Not a longer Technical Approach section. No section at all. In its place, one line under Requirements: "The reorder signal must reflect promo-driven demand within 4 hours of a price change going live, or the item gets flagged for manual review." No batch. No table. No multiplier.

Engineering picked the mechanism this time. They chose an event-triggered recompute, fired the moment a promo price posted, instead of waiting for a clock. The first build had taken three sprint weeks. The fix took two more. Painful, but cheap next to what a wrong requirement, quietly defended as correct for six weekends running, had already cost.

Now walk the next promo weekend forward with that version live. Of the next six store-weekends running a promotion, one store stocked out once, on an item that hadn't been flagged as fast-moving at all. The other 13 held. Not because the forecast got smarter. Because the sentence that started the build finally let someone other than Thandeka decide how to keep it fresh.

And the part I'd tell myself, if I could go back: I was never being sloppy by writing that sentence. I was being helpful. And "helpful" is exactly the disguise a design decision wears when it sneaks into the wrong document.

SPARK, run on the sentence instead of the screen

This is a design question about a habit, not an interface, so the framework still applies, just pointed at a paragraph instead of a product. A question asking "how would you measure this" would reach for LEAD instead; a technical detail sliding into a requirement is a design problem about altitude, and SPARK is built for exactly that.

SPARK, applied to the sentence itself

What stays out of the requirements section, and the one thing that doesn't

And if you want to be sure it really works, try it somewhere else

A county permits office writes PRDs the same rushed way. Different building entirely, same mistake, and a different reason the mechanism shouldn't have been named.

Same framework, a different mechanism locked into the wrong document

S. Perpetua Alonso, product lead on Fennimore County's permit-office tools team. Clerks check each building-permit application against a paper checklist of required documents, one file at a time.
P. The habit worth building: whoever reads the PRD checks that a requirement survives more than one way of building it, instead of trusting a sentence just because it sounds technical.
A. Name the outcome: flag at least 95 of every 100 real missing-document gaps before a reviewer opens the file, and never auto-reject an application. No OCR library, no regex, no table named anywhere in that section.
R. A vague-in-the-wrong-way version, "run OCR library X against every upload and match fields with a regex," locks that library in engineering's mind as the requirement itself. Six months later, when the scanned documents need a different parser, engineering says the PRD requires library X, and swapping it costs two sprint weeks of arguing with a document instead of changing code.
K. Don't name the parsing library, the storage schema, or how the confidence threshold gets tuned. Do keep the reviewer's exact flag message in full, "Missing: proof of ownership," because that wording is product surface, not implementation.

Flashcards (click a card to flip it)

Check yourself Score: 0 / 0