prd-writer

name	prd-writer
description	Use when the user needs to turn verbal requests, scattered ideas, meeting notes, issues, or prior PRDs into a structured, reviewable PRD. Especially use it when the task is to create the next version of an existing PRD by extracting deltas, preserving carry-over decisions, marking removals, and prioritizing scope as P0/P1/P2 or must-have/later.

PRD Writer

Use this skill for two modes:

• New PRD: turn raw inputs into a first structured PRD.
• Iterative PRD: use one or more historical PRDs plus new inputs to produce the next version PRD and make the version delta explicit.

Read references progressively, but default to fuller coverage when the user asks for a PRD rather than a lightweight brief.

At minimum, always anchor on the output template first, then pull in the review passes that are needed to make the PRD complete and reviewable.

Read references with these defaults:

• PRD structure and output shape: references/prd-output-template.md
• Checklist companion shape and checkbox conventions: references/checklist-output-template.md
• Historical PRD versioning and delta handling: references/versioning-diff-strategy.md
• Clarification questions and gap checks: references/requirement-clarification-checklist.md
• Lifecycle and cross-object gap review: references/lifecycle-and-interactions-checklist.md
• Object decomposition, checklist planning, and status updates: references/object-decomposition-and-todo.md
• Multi-document strategy for one version across multiple domains: references/multi-document-prd-strategy.md
• Interaction design and user-flow review: references/interaction-design-checklist.md
• Acceptance and review completion checks: references/acceptance-and-review-checklist.md
• Metrics and observability checks: references/metrics-and-observability.md
• Abuse, misuse, and failure-mode checks: references/abuse-and-failure-mode-checklist.md
• Data model and key-field checks: references/data-model-and-key-fields.md
• Notification and audit checks: references/notification-and-audit-checklist.md
• Migration, rollout, and compatibility checks: references/migration-and-rollout-checklist.md
• Content, copy, and messaging checks: references/content-and-messaging-checklist.md
• React prototype decision and scope strategy: references/react-prototype-strategy.md

When the user asks for a full PRD and does not request a lightweight output, default to including the core review passes for:

• acceptance and review completion
• metrics and observability
• abuse, misuse, and failure modes
• data model and key fields
• notification and audit coverage
• migration, rollout, and compatibility
• content and messaging

Only omit one of these core areas when it is genuinely not relevant. If omitted, say so explicitly in the PRD and give the reason.

Workflow

1. Identify and normalize inputs

Start by listing the actual sources you have. Typical sources:

• verbal request or chat message
• new requirement note
• historical PRD
• issue or ticket
• meeting notes
• strategy note, KPI target, or launch constraint

For each source, capture:

• what it is
• whether it is baseline, change request, or supporting context
• how authoritative it is
• whether it conflicts with another source

If multiple historical PRDs exist, choose one baseline PRD before writing. Prefer the latest approved version, not the latest draft.

2. Decide the document mode

Pick one mode explicitly:

• new_prd: no stable baseline exists
• iterative_prd: there is a baseline PRD and the task is to produce the next version

For iterative_prd, declare:

• baseline version
• target version
• inputs that drive the change

Do not treat an iteration as a blank-page rewrite. Preserve baseline decisions unless new inputs supersede them.

3. Decide the document topology

Choose whether the version should stay in one PRD or split into a same-version PRD bundle.

Default to a single PRD when one reviewer set can still evaluate the scope coherently.

Prefer a multi-document bundle when one version clearly spans separable domains such as:

• business workflow
• permissions / roles
• billing / pricing / quota
• operations / support / internal tooling

Use references/multi-document-prd-strategy.md when the split choice is not obvious.

If you split:

• keep one shared version across the bundle
• keep one shared Checklist.md across the bundle
• make the reason for the split explicit
• keep shared assumptions, object definitions, and unresolved items aligned across documents

4. Extract requirements and change points

Convert raw input into requirement units. Each unit should be a concrete statement about:

• user/problem
• goal or success outcome
• scope item
• constraint
• dependency
• risk
• open question

For iterative work, tag each requirement unit with one of:

• carry_over: keep from baseline as-is
• add: new requirement not in baseline
• modify: baseline exists but needs to change
• remove: baseline item should be dropped
• defer: known request, not in current version scope
• unknown: mentioned but not yet clear enough

If the source material is messy, build the change inventory first, then write the PRD.

5. Stage 1: build the object decomposition and checklist

Before lifecycle review or final PRD writing, produce a separate Checklist.md.

This stage should identify the important objects, actors, sub-objects, and risky relationships in a grouped checklist. The point is to surface hidden scope before prose smooths it over.

Use headings for grouping, but write every actual TODO item in Markdown checkbox form such as:

• - [ ] Define archive behavior for deleted workspaces
• - [ ] [blocker] Confirm billing owner for retroactive refunds
• - [x] Confirm baseline version is v1.4

Do not put this checklist into the main PRD.

For each important object, track at least:

• object identified
• likely owner or domain
• lifecycle still needed or already reviewed
• cross-object interaction checks still needed or already reviewed
• user-flow / interaction-design checks still needed or already reviewed
• requirement coverage still needed or already written
• unresolved gaps confirmed or escalated

If the user wants a visual modeling pass before the full PRD, use Mermaid to express the object tree, lifecycle/state model, or cross-object interaction flow. You can name the section Lifecycle, State Model, or Lifecycle / State Model and explicitly state that Mermaid is the notation used for the breakdown.

Use references/object-decomposition-and-todo.md when the feature is broad enough that direct PRD writing would hide missing objects or coverage gaps.

6. Stage 2: map lifecycle / state model and cross-object interactions

After the object tree exists, inspect each major object or entity named or implied by the requirements. Examples: account, workspace, document, subscription, order, inventory item, approval request, notification rule.

For each major object, check whether the PRD covers its lifecycle well enough for review:

• how it is created
• how it is edited
• when it becomes active, effective, published, or usable
• how it is disabled, deleted, archived, expired, restored, retried, or failed if relevant
• which state changes are irreversible or time-based
• who can trigger each transition
• who can view, edit, approve, or reverse each state

Then check the critical interactions between objects:

• parent-child relationships
• dependency ordering
• state propagation or coupled transitions
• permission propagation
• side effects on notifications, analytics, billing, inventory, limits, quotas, or downstream workflows

Use references/lifecycle-and-interactions-checklist.md when the lifecycle or object interactions are material to the feature.

If you find a lifecycle gap or interaction gap:

• record it explicitly as a PRD gap or missing point
• decide whether it is blocking for scope, review, implementation, or acceptance
• if non-blocking, keep the PRD moving by labeling it as an assumption or open question
• if blocking or likely to change scope or behavior materially, ask the user to confirm and complete it before treating the PRD as reviewable

7. Stage 3: check interaction design and user flow

After object and lifecycle review, verify that the PRD still works as a user experience rather than only as a system model.

Check at least:

• entry point and navigation
• main user path and important branch paths
• back path and exit path
• CTA design, confirmation, undo, and feedback
• loading, empty, error, disabled, pending, and success states
• multi-role handoff points where one actor depends on another

If the feature is logically valid but the user would not know where to start, what happened, or what to do next, treat that as an interaction design gap.

Use references/interaction-design-checklist.md when the feature includes multi-step actions, approvals, risky operations, or user-visible state changes.

8. Run supporting design-process checks

Before the full PRD, check whether the feature also needs explicit coverage for:

• acceptance and review completion
• metrics and observability
• abuse, misuse, or failure modes
• data model and key fields
• notification, audit, or history visibility
• migration, rollout, and compatibility
• content, messaging, empty-state, and error-state wording
• visual asset direction, including whether image generation is available or prompt-only output is needed

Read only the references that are relevant to the feature, but default to broader coverage when generating a full PRD.

Do not force every PRD to use every checklist, but do not silently skip core review areas either. For a normal full PRD, cover the core areas unless you can explicitly justify why a section is not applicable.

For each selected pass, capture:

• the decision that matters for review
• the acceptance or launch implication if the answer changes
• any assumption, open question, or blocker that must remain visible

Keep the output concise but complete. Do not collapse these passes into one-line placeholders if they materially affect implementation, launch safety, review quality, or user understanding.

9. Check unfinished items before the full PRD

Before writing the full PRD, scan the object tree, lifecycle notes, cross-object interaction review, interaction-design review, and any supporting design-process checks for anything still unresolved.

List unfinished items explicitly:

• uncovered objects
• unresolved lifecycle transitions
• unresolved cross-object interactions
• unresolved user flows, states, or role handoffs
• unresolved acceptance, observability, abuse/failure, data-model, audit, rollout, or messaging decisions
• blocked questions that affect reviewability

For each unfinished item, make clear:

• whether it came from the object tree, lifecycle stage, cross-object interaction review, interaction-design review, or another supporting design-process check
• whether it is open, pending, or blocker
• whether drafting can proceed with an assumption or needs confirmation first

Do not pretend the PRD is complete if these remain hidden. Surface them first.

10. Decide what stays, changes, and disappears

For each major section of the baseline PRD, make an explicit decision:

• keep unchanged
• update wording or behavior
• replace completely
• remove from current version

Do not silently drop prior commitments. If a baseline item is no longer in scope, mark it as removed or deferred.

11. Prioritize scope

Every requirement in scope should carry a priority label. Default to P0 / P1 / P2 unless the user asked for another system.

Use this bar:

• P0: required for the target release or the document is not actually shippable
• P1: important, but launch can proceed without it
• P2: useful follow-up, optimization, or later expansion

If inputs are ambiguous, prefer narrower P0 and push uncertainty into P1/P2 or open questions.

12. Stage 4A: prototype decision / prototype handoff

After the staged PRD is clear enough for review, decide whether the work should stop at PRD + interaction design + Mermaid or continue into a low-fidelity or medium-low-fidelity React prototype.

Prefer a prototype when the interaction needs to be experienced rather than only described, especially for:

• multi-step flows
• branch-heavy UX
• role handoff continuity
• page layout and CTA validation
• state-rich flows with loading, empty, error, pending, and success states

Do not jump to prototype when major scope, lifecycle, interaction, or acceptance blockers are still unresolved.

Use references/react-prototype-strategy.md when deciding whether to continue into React code, what the prototype should cover, and which prototype boundaries must stay explicit.

If the answer is yes, make the handoff explicit:

• state whether React prototype work is recommended
• choose low or medium-low fidelity deliberately
• define prototype scope: pages, primary path, important branches, state feedback, key CTA, and multi-step or multi-role handoffs
• define prototype assumptions and boundaries so the artifact is not mistaken for production implementation
• define the mock-data and mock-state strategy needed to make the prototype testable
• after the PRD is written, continue by producing the React prototype code rather than stopping at wireframes, flowcharts, or Mermaid

If the answer is no, say so explicitly and stop at the reviewable PRD plus interaction design and Mermaid artifacts. Keep the blocking gaps visible instead of inventing product decisions just to make a UI compile.

13. Stage 4: write the full PRD or PRD bundle

Use the output structure in references/prd-output-template.md.

Default to completeness over brevity. When generating a full PRD, walk the template section by section and do not silently omit major sections.

Write the main PRD in reviewer-first order:

• start with summary, problem, goals, users, and scope
• explain the proposed workflow before deep requirement detail
• keep lifecycle, interaction, and support checks as synthesized conclusions rather than raw working notes
• keep task tracking, unresolved checklists, and status maintenance in Checklist.md

The output should be reviewable, which means:

• assumptions are labeled
• scope is explicit
• non-goals are explicit
• priorities are attached to requirements
• the earlier object decomposition, lifecycle, and interaction-design work are reflected, not discarded
• unfinished items found before drafting are carried into assumptions, risks, blockers, open questions, rollout notes, content guidance, or acceptance notes as appropriate
• lifecycle, cross-object, and interaction-design gaps are surfaced explicitly
• dependencies and risks are visible
• open questions are separated from decided requirements
• the PRD reads as one coherent document instead of a dump of staged artifacts
• if Stage 4A recommends a React prototype, include the recommendation, scope, assumptions, and mock-data plan in the PRD output so the follow-on prototype work stays bounded

If information is missing:

• keep the section
• label the gap as an assumption, open question, or blocker
• explain why the section cannot yet be filled confidently
• continue drafting unless the gap is truly blocking

For iterative work, include a version-delta section near the top. Use the strategy in references/versioning-diff-strategy.md.

If one version spans multiple distinct domains, you may split it into multiple PRD documents when that improves clarity, ownership, and review quality. Use references/multi-document-prd-strategy.md for split rules.

14. Update the checklist after writing

After generating the PRD, update Checklist.md explicitly:

• check off items only when the PRD now answers them clearly enough for review
• leave unresolved items unchecked and visibly labeled when they are blockers or pending
• do not silently drop unfinished items just because the PRD prose is longer
• if the PRD is split across multiple domain documents, keep shared checklist items aligned across the bundle

15. Handle missing information with discipline

Do not ask a long generic questionnaire up front.

Ask only blocking questions that materially affect:

• target user
• release scope
• priority
• dependency or constraint
• acceptance criteria

Use references/requirement-clarification-checklist.md to decide which gaps are blocking and which can be written as assumptions.

Output Rules

• Write for review, not for inspiration.
• Prefer concrete statements over product prose.
• Default to completeness over brevity unless the user explicitly asks for a lighter output.
• Default to progressive disclosure: object decomposition first, lifecycle/state model second, interaction design / user flow third, full PRD fourth.
• Separate facts, assumptions, and open questions.
• Keep the main PRD readable: it is the review document, not the work log.
• If a historical PRD exists, produce a coherent next-version PRD, not just a diff note.
• If iteration is requested, also include a short delta summary: what is added, changed, removed, deferred, and unchanged.
• Keep unchanged historical content concise, but do not lose important prior decisions.
• When sources conflict, say so and record which source wins or what needs confirmation.
• Before the full PRD, explicitly list unfinished items still present in the object tree, lifecycle stage, cross-object interaction review, or interaction-design checks.
• Do not silently omit major template sections in a full PRD. If a section is not applicable, include it briefly and mark it Not applicable with a reason.
• Do not paste the checklist, TODO tree, or status ledger into the PRD. Put them in Checklist.md.
• Add supporting design-process checks when they materially affect reviewability, acceptance, launch safety, user understanding, rollout confidence, or downstream implementation quality.
• After the full PRD, update Checklist.md rather than adding a TODO status snapshot to the PRD.
• When the Stage 4A decision is yes, continue beyond the PRD into a low-fidelity or medium-low-fidelity React prototype instead of stopping at wireframes or Mermaid alone.
• When one version spans multiple domains with different reviewers, volatility, or compliance sensitivity, prefer a coordinated PRD bundle over one overloaded document.
• Before finalizing, perform a completeness pass against the template and confirm that every major section is either filled, marked with an assumption, or marked Not applicable with a reason.

Minimum Deliverable

Unless the user requests a lighter output, aim to produce:

1. A short input summary and chosen baseline
2. A separate Checklist.md with grouped checkbox TODO items
3. A lifecycle / state model summary for the major objects
4. An interaction design / user-flow summary for the critical paths
5. Supporting design-process passes where relevant: acceptance, observability, abuse/failure, data model, audit, rollout, and messaging
6. An explicit unfinished-items check before the full PRD
7. A version delta summary if this is an iteration
8. A structured PRD or PRD bundle with goals, scope, requirements, priorities, risks, dependencies, open questions, and any relevant supporting design-process sections
9. An updated Checklist.md after the PRD
10. A completeness check confirming that major template sections were not silently skipped