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 (PC.1 through PC.3) to determine:

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 Questions

After scanning, present the user with targeted clarifying questions. Good questions surface missing context that cannot be inferred from the codebase. Typical areas to probe include:

• 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 proceed to structuring until the user has answered enough questions to fill the core sections of the template.

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. Not every PRD requires every section at maximum depth. A small feature enhancement may need a lighter treatment than a net-new product launch. 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

Validate the completed PRD against every item in references/checklist.md. Fix any issues before presenting the final document to the user. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped (with justification).

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 with at least two competitors, honestly acknowledging their strengths. 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 provide hard evidence of real demand from at least three sources: user interviews, survey data, support ticket patterns, usage analytics, beta test results, or revenue impact estimates. Include a "What happens if we don't build this?" subsection that quantifies the cost of inaction. If sufficient evidence does not exist, the PRD should honestly flag this and recommend a validation phase before committing engineering resources.

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 at least two personas in table format. 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.

Source: tercel/spec-forge — distributed by TomeVault.