prd-writing

name	prd-writing
description	Write Product Requirements Documents (PRDs) with structured workflow. Triggers: 'write a PRD', 'product spec', 'feature requirements', 'product requirements', 'create PRD', or any request to document product/feature specifications. Includes codebase analysis, iterative drafting, user story generation with acceptance criteria, and optional GitHub issue creation.

PRD Writing Skill

Create comprehensive PRDs through Context Gathering → Codebase Analysis → Section Drafting → Validation → Issue Creation.

Core Workflow

1. Context Gathering

Ask 3-5 clarifying questions before drafting. Essential questions:

1. What problem does this solve? Who experiences it?
2. Who are the target users/personas?
3. What does success look like? (measurable metrics)
4. Technical constraints, dependencies, or integrations?
5. Timeline, priority level, or phasing needs?

Context dumping encouraged: user research, competitive analysis, stakeholder requirements, existing specs.

⚠️ CRITICAL: Never skip context gathering, even when:

• You have access to existing specs/ideas
• The codebase is already implemented
• You think you understand the requirements
• The user seems eager to get to the PRD

Always ask the 3-5 clarifying questions FIRST. Existing context informs better questions, it doesn't replace them.

Readiness check: Move to drafting when you can discuss trade-offs without needing basics explained.

2. Codebase Analysis

When working in an existing codebase:

• Analyze architecture to identify integration points
• Review existing models, services, and patterns
• Assess technical constraints from current implementation
• Note naming conventions and code organization
• Identify reusable components vs. new development needed

3. Section Drafting

Use the PRD template in references/prd-template.md.

Iterative approach for each section:

1. Ask clarifying questions if gaps exist
2. Brainstorm 5-10 items with user
3. Let user curate/prioritize
4. Draft section
5. Refine based on feedback

4. User Stories

See references/user-stories.md for detailed guidance.

Key requirements:

• Unique ID per story (format: GH-001, GH-002, etc.)
• Cover primary flows, alternative paths, and edge cases
• Include authentication/authorization if applicable
• Every story must be testable
• Clear acceptance criteria (specific, measurable)

5. Validation Checklist

Before finalizing, verify:

• Problem statement is clear and specific
• Target users/personas defined
• Success metrics are measurable
• All user interactions covered (primary + edge cases)
• Each user story is testable
• Acceptance criteria are unambiguous
• Scope boundaries (non-goals) explicit
• Dependencies and risks identified
• Auth/security requirements addressed (if applicable)

6. GitHub Issue Creation (Optional)

After PRD approval, offer to create GitHub issues:

1. Ask: "Would you like me to create GitHub issues for these user stories?"
2. If yes, create one issue per user story
3. Use story ID as issue title prefix
4. Include acceptance criteria in issue body
5. Return list of created issue links

Common Mistakes to Avoid

• ❌ Jumping to drafting because you found idea.txt or existing specs
• ❌ Assuming implemented code means requirements are clear
• ❌ Skipping user input because you think you have enough context
• ✅ Use existing context to ask BETTER clarifying questions

Formatting Rules

• Title: Use title case only for main document title (PRD: {Project Name})
• Headings: Sentence case for all other headings
• Output: Valid Markdown, no dividers/horizontal rules
• References: Refer to project conversationally ("the project", "this feature")
• Quality: Fix grammar, ensure correct casing of proper nouns

Output Location

Default: prd.md in project root. Ask user to confirm or specify alternative.