prd-generator

Skill: PRD Generator

Purpose

Generate a Product Requirements Document from customer evidence and product context. Part of the PRD Pipeline (see CLAUDE.md). Requires HITL-4 approval before the final document is saved.

Input

• Topic: Feature or capability to write the PRD for (e.g. "Vulnerability Scanning Provider Selection", "Native SBOM Generation")
• Insights JSON (optional): Output from merge-insights if the PRD pipeline ran extraction first
• Matching note files (optional): From get-notes-by-topic if running standalone
• Product context files: Automatically loaded from /context/product-context/ based on semantic relevance (see CLAUDE.md Product Context Loading)

If invoked from the PRD Pipeline, insights JSON and matching notes are provided by upstream steps. If invoked standalone ("Write a PRD for [topic]"), gather evidence by reading /context/customer-notes/ and /context/customer-profiles/ directly.

Graph Traversal (Context Enrichment)

After loading semantically relevant product context files:

1. Parse wikilinks and frontmatter: For each loaded product context file, extract related_customers, related_jira, related_docs from frontmatter and [[wikilinks]] from body
2. Load 1-hop neighbors: Read wikilinked customer profiles, related product docs (1 hop only, no recursion)
3. Display traversal log: Show user which related files were loaded
4. Enrich PRD generation: Use the additional context to strengthen Background, Problem, and User Research sections

See CLAUDE.md Graph Traversal for traversal pattern and resolution rules.

Output

A markdown PRD file with YAML frontmatter.

File path: /context/product-context/prds/{slug}-prd-{YYYY-MM-DD}.md

Slugify the topic: lowercase, spaces to hyphens, strip characters that aren't alphanumeric or hyphens, collapse consecutive hyphens. Example: "Vulnerability Scanning Provider Selection" becomes vulnerability-scanning-provider-selection.

Collision handling: If the file already exists, append a counter: -2.md, -3.md, etc. Never overwrite an existing file.

Document Structure

Canonical Section Order

Every PRD must follow this exact section order. Use these headings verbatim:

1. YAML Frontmatter (metadata block)
2. # [Title] (H1 heading matching the project_tag)
3. One-sentence summary (first paragraph after title, no heading)
4. ## Overview
5. ## Background
6. ## Problem
7. ## Personas
8. ## Phases & Requirements Table
9. ## Phase N: [Phase Title] (repeated for each phase)
   • Each phase contains individual requirements with subheadings at H3 level (###)
10. ## User Research
11. ## Out of Scope

Conditional Sections (insert at specific positions)

These sections are optional and insert at specific positions in the canonical order:

• ## Assumptions -- insert after Problem, before Personas
• ## Rollout Plan -- insert after all Phase sections, before User Research
• ## Measuring Success -- insert after all Phase sections, before User Research
• ## Future Possibilities -- insert after Out of Scope
• ## Analytics Requirements -- insert after all Phase sections, before User Research
• ## Pricing & Packaging -- insert after Out of Scope
• ## Breaking Backwards Compatibility -- insert after Background, before Problem
• ## Appendix -- always last section

Only include conditional sections when the evidence or topic explicitly warrants them. If you're unsure whether a conditional section is needed, omit it.

Required Section: Related Context

The ## Related Context section is always included at the end of every PRD (after Out of Scope and any conditional sections). This section contains wikilinks to customers, Jira issues, and related docs. See details in the "Out of Scope" section above.

Prohibited Sections

Never include these generic PM template sections. They do not match [PM_NAME]'s PRD format:

• Executive Summary
• Solution Overview
• Technical Considerations
• Risks & Mitigations
• Go-to-Market
• Success Metrics (use "Measuring Success" if needed)
• Open Questions (questions belong inside requirements as "Considerations")
• Dependencies
• Timeline / Milestones
• Resources Required

Section-by-Section Rules

YAML Frontmatter

---
project_tag: "Human-readable project name"
one_line_description: "One sentence: what this PRD is and why it matters"
doc_type: prd
date_ingested: YYYY-MM-DD
related_customers: []  # Array of canonical customer names cited in User Research
related_jira: []       # Array of Jira issue keys referenced in PRD
related_docs: []       # Array of related product context file slugs
---

• project_tag: Use the topic name as provided by [PM_NAME]
• one_line_description: One sentence capturing the feature and its value to [PRODUCT] customers
• doc_type: Always prd
• date_ingested: Today's date
• related_customers: Extract from User Research section -- list canonical customer names
• related_jira: Extract from Background and throughout PRD -- Jira issue keys ([PROJECT_KEY]-XXX pattern)
• related_docs: Empty initially (can be manually populated later)

One-Sentence Summary

A single sentence (max 30 words) that captures what the feature does and why it matters. This is the first line after the frontmatter heading. It should be understandable by someone with no context on [PRODUCT].

Overview

2-4 paragraphs covering:

• What the feature is at a high level
• Why it matters to [PRODUCT] customers (ground in evidence)
• How it fits into the broader product vision
• What's in scope for this PRD (if the topic is broad)

Write in plain language. Avoid jargon unless it's domain-standard (CIS, SBOM, CVE). Reference customer evidence naturally -- "Customers with existing [TOOL_A] deployments have asked for..." not "Per the insights JSON..."

Background

Context a reader needs to understand the problem space:

• Current state of the relevant feature area in [PRODUCT]
• How customers solve this problem today (workarounds, third-party tools, manual processes)
• Relevant industry context (standards, competitor capabilities, market trends)
• Any prior internal work (engineering docs, spikes, previous PRDs)

Load relevant product context files from /context/product-context/ using semantic matching. Reference engineering docs and prior art summaries if they exist for this topic.

Problem

Structure as Jobs To Be Done (JTBD). For each distinct problem:

**When** [situation the user is in],
**I want** [action they want to take],
**so that** [outcome they're trying to achieve].

Each JTBD should be grounded in real customer evidence. After the JTBD statement, include a brief narrative (1-2 sentences) connecting it to observed customer behavior.

Aim for 3-6 JTBDs depending on topic complexity. Group related JTBDs under sub-headings if the problem space has distinct facets.

Personas

For each persona:

• Name: Role title (e.g. "Platform Engineer", "Security Architect", "DevOps Team Lead")
• Description: 2-3 sentences covering what this persona does, what they care about, and how they interact with [PRODUCT]
• Key needs: Bulleted list of what this persona specifically needs from the feature

Ground personas in real customer roles observed in notes. [CUSTOMER_1]'s security architect [CONTACT_NAME], [CUSTOMER_2]'s multi-cloud platform team, [CUSTOMER_4]'s compliance-focused DevOps team -- abstract from these to general personas without naming specific individuals.

Phases & Requirements Table

A summary table showing all phases and their requirements at a glance:

| Phase | Requirement | Description |
|-------|-------------|-------------|
| Phase 1 | [Req title] | [One-line description] |
| Phase 1 | [Req title] | [One-line description] |
| Phase 2 | [Req title] | [One-line description] |

Phase 1 is the minimum viable scope that addresses the core JTBD. Phase 2+ are incremental expansions. If the evidence only supports one phase, that's fine -- don't invent phases for completeness.

Phase Requirements (repeated per phase)

For each phase, a section heading (## Phase N: [Phase Title]) followed by individual requirements.

Each requirement gets:

Requirement Title

A descriptive title in sentence case (e.g. "Support [TOOL_A] as a vulnerability data provider"). This is an H3 heading (###).

Narrative

A paragraph explaining what this requirement is, why it matters, and how it connects to the broader feature. Write for a reader who hasn't seen the rest of the PRD -- each requirement narrative should stand on its own.

Acceptance Criteria

Bulleted list using "must" language. These are pass/fail conditions for the requirement being complete:

**Acceptance Criteria**
- Administrators must be able to [specific action]
- The system must [specific behavior] when [specific condition]
- [Feature] must [specific outcome] for all [scope boundary]

Aim for 3-6 acceptance criteria per requirement. Each criterion should be testable -- "must be fast" is not testable; "must return results within 5 seconds for registries with up to 10,000 artifacts" is.

Depth Rule: Acceptance criteria must describe behavioral requirements (what the user can do or observe), not implementation details (how it's built). This is a PRD, not an engineering design doc.

What belongs in AC:

• User-visible actions ("Administrators must be able to select their scanning provider in registry settings")
• System behavior from the user's perspective ("The system must apply the new provider to all scans started after the change")
• Observable outcomes ("Vulnerability data must be stored with full provider attribution")
• Non-functional requirements at a product level ("Scan results must be displayed within 5 seconds for registries with up

Content truncated.