prd-generation

name	prd-generation
description	Generates professional Product Requirements Documents (PRDs) following industry-standard methodologies. This skill activates when the user asks to write PRD, create a product requirements document, draft product requirements, do product planning, do feature planning, write a product spec, or create a product document. It synthesizes best practices from the Google PRD framework, the Amazon Working Backwards methodology, and the Stripe Product Spec approach to produce comprehensive, actionable PRDs tailored to the user's project.
instructions	Generate PRDs by combining the structured rigor of Google PRD templates, the customer-centric narrative of Amazon Working Backwards, and the engineering-precision of Stripe Product Specs. Follow the five-step workflow defined in this skill, reference the template at references/template.md, and validate output against the checklist at references/checklist.md.

PRD Generation Skill

What Is a PRD?

A Product Requirements Document (PRD) is the central artifact that bridges product strategy and engineering execution. It captures the why, what, and how of a product initiative so that every stakeholder -- from designers and engineers to leadership and QA -- operates from a single source of truth. A well-written PRD reduces ambiguity, prevents scope creep, and provides a measurable framework against which the team can evaluate success.

Within the product development lifecycle a PRD typically sits between the discovery phase (where problems are identified and validated) and the design/engineering phase (where solutions are built). It is not a static document; it evolves through drafts, reviews, and revisions as the team's understanding deepens. This skill treats the PRD as a living document and structures it accordingly.

Five-Step Workflow

Every PRD generated by this skill follows a disciplined five-step process. Each step must be completed before moving to the next.

Step 1 -- Understand Context

Before writing a single line, scan the project to build situational awareness.

@../shared/project-context.md

Execute the Project Context Protocol. Prefer its PC.0 fast path — resolve <sf_scripts> (see @../shared/scripts.md) and run python3 "<sf_scripts>/sf-scan.py" --root "<project_root>", which returns the frameworks and signals (languages, DB/auth signals, test command) plus the existing-doc inventory as documents and document_index (prior PRDs, technical designs, or ADRs with their declared IDs) in one pass. Fall back to the manual PC.1–PC.3 scan only if python3 is unavailable or the script is not found. Use the scan output as the starting inventory, then apply the judgement the script does not:

1. Project structure and existing documentation (PC.1)
2. Tech stack and framework (PC.2)
3. Project profile (PC.3) — Web API, CLI Tool, Frontend, etc.

Additionally: 4. Scan the docs/ directory (if it exists) to find prior PRDs, technical designs, or ADRs. Understanding what has already been decided prevents contradictions and duplicated effort. 5. Identify domain language and team conventions so the PRD speaks the same language as the codebase.

This scanning step ensures the generated PRD is grounded in the actual project rather than generic boilerplate. The detected project profile informs which sections of the PRD need the most detail (e.g., a CLI tool needs different success metrics than a Web API).

Step 1.5 -- Doc-First Discipline (Mandatory)

Before clarifying questions or writing any content, the doc-first discipline applies. Read the existing documentation, identify what already covers the topic, and decide for each section whether to REUSE (reference existing), EXTEND (edit existing in place), or NEW (genuinely missing). The default for any topic that already has coverage is to extend in place — never to create parallel prd-v2.md files, never to append ## Update blocks at the end, never to leave deprecated sections strikethrough'd. Documentation is single-source-of-truth, not version history.

The full discipline, the four rules, the pre-generation checklist, and the anti-patterns to avoid:

@../shared/doc-first.md

You MUST run the pre-generation checklist (the five questions) from doc-first.md before proceeding to Step 2. If existing docs cover any of the topics this PRD will discuss, you must:

1. List the existing files and sections that overlap (with file:line references)
2. Decide REUSE / EXTEND / NEW for each topic
3. Bias toward EXTEND — opening the existing file and modifying it — over NEW
4. Identify which existing requirement IDs, section titles, and defined terms must remain stable for traceability
5. Surface any downstream documents (SRS, tech-design, feature specs, README) this generation will affect, so the user knows the propagation cost

If the project shows signs of doc drift (multiple prd-*.md files, obvious duplication, contradictions surfaced during the scan), warn the user before proceeding and recommend they run /spec-forge:analyze or /spec-forge:propagate first to consolidate.

If a usable existing PRD already covers most of what the user is asking for, the right action is edit it in place, not generate a new file. Only create docs/{feature}/prd.md from scratch when no relevant existing PRD exists.

---

Step 2 -- Clarify Only What You Cannot Infer

First infer every answer you can from the scanned project context, any existing docs, and the user's request — and state those inferences as explicit assumptions the user can correct. Then ask the user only the questions whose answers materially change the PRD and cannot be inferred. The areas that genuinely tend to need the user:

• The target user segment and their primary pain points.
• Business objectives and how success will be measured.
• Known constraints (timeline, budget, regulatory, technical debt).
• Stakeholders who must review or approve the PRD.
• Dependencies on other teams, services, or third-party systems.

Do not march through a fixed questionnaire or re-ask anything the scan or existing docs already answer; a strong scan often makes most questions unnecessary. Proceed to structuring once you have enough — from inference plus targeted answers — to fill the core sections; capture any remaining unknowns as open questions rather than blocking on them.

Step 3 -- Structure Design

Using the answers from Step 2 and the context from Step 1, decide which sections of the template are relevant and how deep each section needs to be. No forcing irrelevant sections — adapt to the actual project profile. Not every PRD requires every section at maximum depth: a small internal feature does not need TAM/SAM/SOM market sizing, a full competitive landscape, a GO/NO-GO feasibility verdict, or a Gantt timeline the way a net-new product launch does. Sections that do not apply to the project profile should be omitted or explicitly marked N/A with a one-line reason, rather than filled with placeholder ceremony. Do not delete template sections wholesale — mark the inapplicable ones N/A so the structure stays legible. Map the user's input to the template sections defined in references/template.md and plan the Mermaid diagrams that will be included.

Step 4 -- Content Generation

Write the PRD by filling in each section of the template. Follow the writing guidelines described below. Generate all Mermaid diagrams inline. Assign requirement IDs, priorities, and success metrics as you go.

Step 5 -- Quality Check

Run the structural gate with the script, then apply judgement with the checklist:

python3 "<sf_scripts>/sf-verify-doc.py" "<prd.md>" --strict

This deterministically confirms the title, expected sections, ID format/uniqueness, and the absence of leftover template placeholders. Fix everything it flags. Then load references/checklist.md and evaluate the items the script cannot judge — evidence quality, competitive-analysis honesty, whether each section is applicable to the project profile. The document is only written to disk once the structural gate passes and the judgement items hold. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped (with justification). (If python3 is unavailable, run every checklist item by hand.)

Key Sections and Writing Guidelines

The PRD template contains twenty sections. The following guidelines apply when writing each one.

Document Information and Revision History. Fill in all metadata fields. Use the current date. Set the initial version to 0.1 and the status to Draft. The revision history table must have at least one entry corresponding to the initial draft.

Executive Summary. Write two to four sentences that a busy executive can read in under thirty seconds. State the problem, the proposed solution, and the expected impact. Avoid jargon.

Product Overview and Background. Provide enough context so that a new team member can understand why this initiative exists. Reference prior PRDs or design documents when they exist in the repository.

Market Research and Analysis. This section proves that the product addresses a real market opportunity, not an imagined one. Include market sizing (TAM/SAM/SOM) with cited sources — never fabricate market data. Map the competitive landscape, honestly acknowledging each competitor's strengths. Aim for at least two competitors, but treat that as a target, not a floor: if only one genuine competitor exists — or the only real alternative is the status quo (doing nothing, a manual workaround, an existing internal tool) — document that single real competitor rather than inventing others to hit a number. Clearly articulate what differentiates this product. Include industry trends that support the initiative's timing. This section should answer: "Is there a real market for this?"

Value Proposition and Validation. This is the anti-pseudo-requirement section. State the value proposition in one sentence. Then document the hard evidence of real demand that actually exists — drawing on user interviews, survey data, support ticket patterns, usage analytics, beta test results, or revenue impact estimates. Aim for three or more independent sources, but treat that as a target, not a hard floor: document the real evidence you have rather than inventing more to reach a count — one solid, honestly labelled data point beats three fabricated ones. Include a "What happens if we don't build this?" subsection that quantifies the cost of inaction. When the evidence is thin, the first-class response is to say so: honestly flag the insufficient evidence and recommend a validation phase before committing engineering resources. That path is always acceptable and is never overridden by the source-count target.

Feasibility Analysis. Assess technical feasibility (technology readiness, infrastructure, POC status), business feasibility (revenue model, ROI, strategic alignment), and resource feasibility (team availability, skills, budget, timeline). Conclude with a clear GO / CONDITIONAL GO / NO-GO verdict. A well-reasoned NO-GO saves more resources than a poorly justified GO. Do not rubber-stamp everything as GO.

Problem Statement. Structure this section around three lenses: the current situation, the pain points users experience, and the opportunity that addressing those pain points unlocks. Use data or user quotes when available.

Goals and Non-Goals. Goals must be specific, measurable, and time-bound. Non-goals are equally important; they tell the team what is explicitly out of scope so energy is not wasted on tangential work.

User Personas. Define the personas the evidence actually supports, in table format. Aim for at least two, but treat that as a target, not a floor: if only one real user type is grounded in the evidence, define that one persona rather than inventing a second to hit a number. Each persona should have a name, role, demographic summary, core needs, and pain points. Personas must be referenced later in user stories.

User Stories and Acceptance Criteria. Every user story follows the canonical format: "As a [user type], I want [action] so that [benefit]." Each story must have at least two acceptance criteria written as testable conditions.

Functional Requirements Overview. List requirements in a table. Each row gets a unique ID following the naming convention described below, a short feature name, a description, a priority, a Priority Rationale, and a status. The Priority Rationale must answer "why this tier and not the one above or below" — referencing user impact, business consequence, or the presence/absence of an acceptable workaround. Never assign a priority without this justification; undefended priorities are flagged during the quality check.

Success Metrics. Every metric must have a target value and a measurement method. Include the current baseline when known. Tie metrics back to the goals defined earlier.

Timeline, Milestones, and Risk Assessment. Use Mermaid Gantt charts for the timeline. Risks go in a matrix with likelihood, impact, mitigation strategy, and an owner.

Dependencies, Open Questions, and Appendix. Capture anything that blocks progress, anything still unresolved, and any supplementary material such as raw research data, detailed competitive analysis spreadsheets, or wireframe links.

Mermaid Diagrams

Mermaid diagrams make the PRD scannable and visually informative. This skill uses three types of diagrams.

User Journey Flowcharts. Use graph TD or graph LR to show the step-by-step path a user takes through the feature. Include decision nodes for branching logic and clearly label happy-path versus error-path flows.

Feature Architecture Diagrams. Use graph TD to show the high-level component relationships: which services, APIs, data stores, and external systems interact. This is not a detailed system design; it is a conceptual map that helps non-engineers understand the moving parts.

Gantt Charts for Timelines. Use gantt to lay out phases, milestones, and dependencies over time. Include sections for design, development, testing, and launch. Mark critical-path items.

All Mermaid code blocks must use the ```mermaid fence so they render correctly in GitHub, GitLab, and most Markdown viewers.

PRD ID Naming Convention

Every requirement, risk, and trackable item in the PRD receives a unique identifier following this pattern:

PRD-<MODULE>-<NNN>

• PRD is the fixed prefix indicating the document type.
• MODULE is a short uppercase code (three to five characters) representing the feature area or module. Examples: AUTH, PAY, DASH, NOTIF, ONBRD.
• NNN is a zero-padded three-digit sequence number starting at 001.

Examples: PRD-AUTH-001, PRD-PAY-012, PRD-DASH-003.

This convention ensures IDs are grep-friendly, sort-friendly, and unambiguous across multiple PRDs in the same repository.

Feature Prioritization

Requirements are prioritized using a three-tier system.

• P0 -- Must Have. The feature cannot ship without these requirements. They address core user needs or regulatory obligations. If a P0 item is cut, the launch must be reconsidered.
• P1 -- Should Have. These requirements significantly improve the user experience or business outcome but are not strictly necessary for a minimum viable launch. They are the first candidates for inclusion if the timeline allows.
• P2 -- Nice to Have. These are enhancements, polish items, or forward-looking capabilities that can be deferred to a subsequent release without materially affecting the launch.

When assigning priorities, tie each decision back to the goals defined earlier in the document. If a requirement does not clearly support a stated goal, question whether it belongs in this PRD at all.

Reference Files

This skill relies on two reference files stored alongside it.

• references/template.md -- The full PRD template with placeholder text for every section. The generated PRD is built by filling in this template.
• references/checklist.md -- A quality checklist organized into four categories (Completeness, Quality, Consistency, Format). The checklist is used during Step 5 to validate the finished document.

Always read both files before generating a PRD so that any updates to the template or checklist are picked up automatically.

Output Location

The finished PRD is written to:

docs/<feature-name>/prd.md

where <feature-name> is a lowercase, hyphen-separated slug derived from the feature name (for example, docs/user-onboarding/prd.md or docs/payment-retry-logic/prd.md). If the docs/<feature-name>/ directory does not exist, create it. If a file with the same name already exists, confirm with the user before overwriting.