Twelve Polished Pages, and Half of Them Were Never Said

Agents can draft a product requirements document, but people own ideation, and the only Shape gate is an owner who can explain the need without reading it.

Rick Hightower

Cover image for “Twelve Polished Pages, and Half of Them Were Never Said” by Rick Hightower

Agents can draft the product requirements document. They cannot decide what the business wants, and Shape keeps that line visible.

A one-line idea comes back as twelve polished pages, and the sponsors reject half because the agent wrote requirements nobody said. Unread requirements are the most expensive output of the first stage, because every later stage treats them as truth.

In this article: A fluent product requirements document is a risk when the agent filled the gaps. Shape is a wizard with one gate: the owner can explain the need without reading it. The contract, the memory, and a fictional workspace export show how that gate holds.

A team hands an agent a one-line idea and asks for a product requirements document. Ten minutes later: twelve polished pages, personas, journeys, metrics, edge cases, a phased rollout. The sponsors reject half, because half was never said. The agent filled gaps, pulled ideas out of context, and wrote as if it had been in the meeting. The pages nobody challenged were often the pages nobody read. They return later as features no one asked for, or as constraints build agents enforce.

Invented and unread requirements are the risk of Shape, the stage that decides what is worth building. Later stages amplify it: a vague need becomes vague tickets, then confident code, then a review queue of the wrong thing. If a factory multiplies effort, it had better multiply what the business wants. People own ideation. The agent makes that ownership cheaper. It does not take the decision.

What the stage may do

Table: Part, Shape. Rows: Trigger; Work; Independent check; Memory; Stop condition.

Shape's loop has five parts. The Part column names each part, and the Shape column says what that part is for this stage.

  • Trigger. Shape starts when a person brings a problem or opportunity, or when a timer produces a feedback digest.
  • Work. The agent asks questions, offers options, clusters signals, explains terms, and drafts the PRD.
  • Independent check. The app owner reads the PRD and can explain it.
  • Memory. The stage recalls related decisions, ADRs, research, and ideas already rejected.
  • Stop condition. Shape ends with an agreed outcome, or with a recorded decision to stop.

Blank-page drafting shrinks. Approving the intent that every later stage builds on grows. A person brings a complaint, a sales request, a support hunch, or a deadline. A timer can cluster a week of feedback instead. Three bans:

  • Never invent a requirement. Unsaid means an open question, not a fact.
  • Never decide priority. Tradeoffs are in scope. The pick is not.
  • Never treat silence as approval. An unanswered question stays open, and a timeout is not a yes.

One wizard, one gate

Shape works as a wizard: skills, hooks, and commands from a one-line idea to a PRD the owner can defend. Not as an agent that runs off and decides.

The L1 wizard: one-line idea, open questions, one decision gate.

Questions run in order: who has the problem, how they cope, what would change, what is out of scope. Stuck owners get two or three options. Explain a term like "tenant isolation" at the reader's level. Many owners think better talking than typing. Owner words are requirements. Everything else is a question.

How the requirement arrives matters. Across 15 models and more than 200,000 simulated conversations, every model did worse when a task arrived in pieces than when it arrived whole, an average drop of 39%. A wrong turn early rarely gets repaired. The wizard interviews, writes a spec to disk, and the consuming stage starts a fresh session that reads the spec whole. A long chat is the weakest input a factory can get.

Interview, write the spec, and let a fresh session read it whole.

A hook locks the signed decision so a later session cannot quietly rewrite it. Reopening Shape is the only edit. PRD Forge, Claude Code's product-management skills, and Spec Kit's specify step already follow this shape. Use whichever matches the template. The pattern is the requirement, not the tool.

Explain it, or you have not approved it

The app owner decides whether the problem is worth solving and what success means. The owner must explain the PRD without reading from it. Otherwise they received it. They did not approve it. Later stages will treat an unread line as truth.

Score the draft the way a loop scores code: testable requirements, an observable success measure, nothing in scope that contradicts a linked ADR. The score spends judgment on substance. It does not replace the owner. An approved PRD then chains from the task to its ticket, the journey, and the product manager on the roadmap.

Two real endings: an agreed outcome, or a recorded stop. A stage that can only say yes is not deciding. Waiting is not an ending.

Approved or stopped. Waiting never becomes a yes, and only an explained decision locks.

Plan, the stage that turns the need into tickets, should reject a need with open questions in the wrong places, the way an API rejects a bad request. "Out of scope" is the line a ticket reviewer cites when a ticket grows.

The contract on an agreed need: problem, outcome, success measure, scope, constraints, open questions, and an explicit decision.

Table: Field, What it holds. Rows: Problem; Outcome; Success measure; In scope / out of scope; Constraints; Open questions; Decision.

The contract on an agreed need has seven fields. The Field column names each one, and the What it holds column says what goes in it.

  • Problem. It records who has the problem, and how they cope today.
  • Outcome. It says what changes for users if the work succeeds.
  • Success measure. It says how we will know, and when we will check.
  • In scope / out of scope. The owner states both. The agent does not infer them.
  • Constraints. It lists linked ADRs, policies, and deadlines.
  • Open questions. It holds anything the agent proposed that the owner has not confirmed.
  • Decision. It records approved or stopped, by whom, and when.

Memory, then a second pass after release

The same idea returns every few quarters from someone who never heard it was stopped. Without a record, the wizard helps them write it again.

Any reviewable store works: ADRs in Git, a wiki, or a knowledge graph. The OKF plugin family is one example of a shared git-native tree. Research Knowledge Capture holds claims and sources. Project Knowledge Capture holds the why: PRDs, ADRs, and why an idea was cut. Show the owner the constraining decisions and the rejected cousins before drafting, then record the need, the measure, and the cuts, stops included. Three sharp decisions beat thirty loose documents, and the ones in the middle are the easiest to ignore. One repo's instructions cannot say that another team already owns the problem. Markdown in Git can, because agents read it and people review it like code.

Shape is both ends of the loop. After release it asks whether the change did what the measure said.

Shape before the build, and Shape again after release.

Production with no users is not a slow success. It is a postmortem, and improvement needs product feedback, not only engineering metrics. The agent can gather usage and the support tickets that name the feature. The owner decides what they mean. "We do not know yet" is allowed when too few people tried it, and that answer belongs beside the original need.

Start smaller than the tooling

No published study, in the research behind this design, shows that agent-written PRDs produce better products. Practitioner notes, framework docs, and vendor pitches are what exist. Keep Shape human-led. Do not skip it.

Swap the scaffolding freely. PRD Forge and Claude Code's product-management skills draft inside the coding agent. GitHub Spec Kit starts from a constitution and a specify step. BMAD Method uses analyst and product-manager personas. ArcKit leans on principles, business cases, and risk. A few skills tuned to your template and your ADRs often match any of them.

Do not automate first. One PRD in the owner's own session is enough. Skepticism usually gives way after a cycle or two, once the draft keeps their words and marks its guesses. Add the lock when the template settles, and the post-release check when a feature is worth measuring. Building review first is reasonable. Add the wizard when a later stage can actually consume the artifact.

One line in, a locked need out

The workspace export is fictional. A customer-facing team says users want to download their data.

Who, and why: workspace admins, for audits. What "their data" means is the real question. "Everything the user can see" searches every workspace they belong to. The wizard puts an existing tenant-isolation ADR on the table and offers two options, workspace-only or cross-workspace with new access rules. The owner picks workspace-only and writes cross-workspace search out of scope. Success is an audit export by pilot admins with no support ticket. They can explain it without the page, so the hook locks it, and memory records the cut. The out-of-scope line is what a ticket reviewer should quote when a ticket starts to grow.

Do this today

  • Draft one real need with a PRD skill in the owner's own session. Leave the stage unautomated.
  • Turn every sentence the owner did not say into an open question.
  • Refuse approval unless the owner can explain the PRD with the page closed.
  • Store stopped ideas, and why, where people and agents both read. ADRs in Git are enough.
  • After a release that matters, compare use with the success measure and file the result beside the need. "We do not know yet" is a finished answer.

Multiply the right sentence

A fluent PRD is cheap. An agreed need is not. Mark the guess, or every later stage will build on a sentence nobody said. Keep the line between what the owner said and what the agent proposed. Lock only what they can explain. Allow a stop. Run Shape again after release, because shipping is not the measure.


This is Part 2 of "AI Software Factory Series," a 17-part guide to building an AI software factory with human gates.