tercel/spec-forge/prd-generation

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:

1. 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.
2. 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 nineteen sections. The following guidelines apply when writing each one.

Where the PRD stops. The PRD is the business case and product definition: why this is worth building, for whom, what is in scope, at what priority, by when, and how success is measured. It is a decision document read by stakeholders before commitment, and it is largely frozen once the decision is made. It is not the delivery contract. The precise system behavior that an implementer is held to — field-level input rules, state machines, permission matrices, error codes, Given/When/Then acceptance criteria, interface contracts — lives in the SRS (docs/{feature}/srs.md), which continues to evolve through delivery. Keeping the two separate is what allows a requirement to change without touching market sizing, and what keeps internal go/no-go reasoning out of a document handed to an implementation vendor. When you catch yourself writing a testable condition in the PRD, that content belongs in the SRS.

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.