PRD writing
Turn the confirmed product inputs and decisions into the final PRD. This is a rendering step, not another brainstorm. Write once in normal operation; repair only when deterministic validation names a specific defect.
Source of truth
Read the confirmed inputs and requirement paths supplied by the workflow. When the cumulative decision artifact exists, its answers are authoritative; when it does not, no extra interview decisions were needed. Do not scan the repository, reopen product decisions, add plausible features, or infer technical design. If a required answer is absent, stop instead of filling space.
For a decision whose source is user-answer, use only its answer. Its unaccepted proposal is
context, not permission to complete a partial answer. Stop without writing if a must_resolve fact
is absent, a material value remains vague, or two confirmed decisions conflict.
Render every decision by its source. accepted-proposal, chosen-alternative, user-answer, evidence (settled by the cited
source), and
user-raised are confirmed requirements. An assumption goes under Constraints and assumptions,
plainly marked as an unconfirmed assumption; it may shape scope but must stay visibly unverified. A
deferred decision is not a requirement: list it under Dependencies and risks as an open item
with the user's note, give it no acceptance criterion, and never write around it as if decided.
Required structure
Start with this compact document header:
# <Concise feature name> — PRD
**Feature slug:** `<workflow-supplied slug>`
**Status:** Ready for review
Derive the feature name from the confirmed goal without adding scope. Do not add revision history, decision IDs, authors, or decorative metadata.
Use these exact level-2 headings in this order:
SummaryProblem and contextUsers and jobsGoals and success signalsNon-goalsFunctional scopeNon-functional requirementsConstraints and assumptionsAcceptance criteriaDependencies and risksPriorities and phasingReferences
Use identifiers only in Acceptance criteria. Write every criterion as a sequential observable
bullet beginning AC-01:, AC-02:, and so on. Do not put B1, B2, FR-*, REQ-*, question
IDs, or other traceability codes in any other section.
Non-functional requirements lists one bullet per confirmed target, each measurable and named by
what it constrains: volume and growth, response time, availability and recovery, data retention,
security or compliance obligations, accessibility. Write the number the decision or source gives
("p95 under 300 ms at 50 requests/second"); never invent one. When nothing applies beyond the
service's existing standards, write None beyond the existing service standards.
Before adding prose, create all twelve headings in the required order. Before completing, check that every in-scope actor permission, state transition, limit, conflict, override, and recovery rule from the confirmed decisions has an observable acceptance criterion. Non-goals do not need one.
Plain technical English
- Put the decision or idea first.
- One idea per sentence; one topic per paragraph.
- Prefer short bullets for scope, non-goals, risks, and acceptance criteria.
- Use active voice and name who does what.
- Use concrete words. Avoid
leverage,facilitate,robust,seamless,ecosystem, and other decorative language. - Define a necessary technical term once. Cut terms the product reader does not need.
- Preserve the user's meaning and terminology.
- State each idea once. No recap paragraphs, filler, marketing claims, or repeated rationale.
- Expand only when precision would otherwise be lost.
Concision
Use the shortest wording that preserves every confirmed product fact. Remove repetition, filler, and generic explanation; prefer bullets or compact tables when they make the content easier to scan. There is no word-count target or ceiling. Never omit, merge, or soften a requirement, edge case, constraint, risk, or acceptance criterion merely to shorten the document. When precision needs more context, include it.
Validate before returning
Run the workflow-supplied validator after writing. Allow its mechanical-fix mode to normalize line wrapping and acceptance-criteria numbering. If it still reports a defect, repair only that defect inside this same call and validate again. Do not return success with a failing artifact.
Normalize mode
When the workflow supplies the client's own PRD (any format) as the source, restructure it into the required structure instead of re-deriving it. The client's document is the confirmed input:
- Keep its facts, scope, priorities, limits and names; keep its wording unless a sentence is unclear. Move content into the matching section; never drop a requirement because it does not fit neatly — put it in the closest section.
- Add nothing the source does not say. Turn each testable requirement into an acceptance criterion; a requirement that cannot be tested as written is a gap, not a criterion you complete yourself.
- List the gaps as a question queue in the format the workflow's question validator accepts: only material product facts the source leaves unsettled (a missing actor, limit, failure behaviour, success signal, non-goal, or a vague criterion), each with a grounded recommendation and the facts an answer must settle. Never ask what the source already answers, about headings, or about technical design.
- Where a section depends on an open gap, write the recommendation and mark it "(to confirm)";
once the decisions exist, replace each mark with the decision, rendered by its
sourceas above. - Never edit the source documents.
Repair mode
When the workflow supplies validator feedback, change only the named defects. Do not rewrite
unrelated sections or make the document longer unless the missing precision requires it. Preserve
existing acceptance-criteria IDs when their meaning is unchanged; otherwise restore one unique,
gap-free AC-01 sequence.
Revision mode
When the workflow supplies reviewer feedback on an existing PRD, apply it as a targeted edit:
change only the sections the feedback affects, keep every other section, confirmed decision and
ID unchanged, and read only the sources the change needs. Do not regenerate the document. If the
feedback needs a new product decision that the confirmed decisions cannot settle, do not guess: leave the
document unchanged and report needs_clarification as true so the decision is clarified first.
Safety
Write only the workflow-supplied PRD artifact (and, in normalize mode, its question queue). Never edit the client's source documents, other requirements, confirmed context, code, or run state.
Output contract
Return summary: one short sentence stating that the final PRD was written (in normalize mode,
how many gaps remain open) or which validator defects were repaired. In revision mode also return needs_clarification: true only when
the feedback needs a product decision that must be clarified before editing, else false.