From d66fde9999eefbed15591acd11a5571c962f5f64 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:49:39 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 64 ++ skills/prd-generator/SKILL.md | 476 ++++++++++++ .../references/metrics_frameworks.md | 733 ++++++++++++++++++ .../prd-generator/references/prd_template.md | 572 ++++++++++++++ .../references/user_story_examples.md | 667 ++++++++++++++++ skills/prd-generator/scripts/generate_prd.sh | 395 ++++++++++ skills/prd-generator/scripts/validate_prd.sh | 298 +++++++ 9 files changed, 3220 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/prd-generator/SKILL.md create mode 100644 skills/prd-generator/references/metrics_frameworks.md create mode 100644 skills/prd-generator/references/prd_template.md create mode 100644 skills/prd-generator/references/user_story_examples.md create mode 100755 skills/prd-generator/scripts/generate_prd.sh create mode 100755 skills/prd-generator/scripts/validate_prd.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..2e10776 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "prd-generator", + "description": "Generate comprehensive Product Requirements Documents (PRDs) for product managers. Use this skill when users ask to 'create a PRD', 'write product requirements', 'document a feature', or need help structuring product specifications.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "James Rochabrun", + "email": "jamesrochabrun@gmail.com" + }, + "skills": [ + "./skills/prd-generator" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..41ae5cf --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# prd-generator + +Generate comprehensive Product Requirements Documents (PRDs) for product managers. Use this skill when users ask to 'create a PRD', 'write product requirements', 'document a feature', or need help structuring product specifications. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b6a58d2 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,64 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jamesrochabrun/skills:prd-generator", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "35ac800f8419311e319c9f66594e835b9593d1ed", + "treeHash": "a2b2e93155c9780557e5195cd862fdda6a084013b56d27e8e4876d751e7ff8f2", + "generatedAt": "2025-11-28T10:17:53.267850Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "prd-generator", + "description": "Generate comprehensive Product Requirements Documents (PRDs) for product managers. Use this skill when users ask to 'create a PRD', 'write product requirements', 'document a feature', or need help structuring product specifications." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "4f840c20cb88516b69dc7a5fe8266d2125d6a61d1cf67982b2c4da9f6435dea8" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d15a6ebf93a14c01c6dac48ac5139560eeb63dbe56e28476c2d81d02b69d717e" + }, + { + "path": "skills/prd-generator/SKILL.md", + "sha256": "37024f403238962eceed83399637945248e11c4a2597eb95e980301b7de05438" + }, + { + "path": "skills/prd-generator/references/metrics_frameworks.md", + "sha256": "a814edd717c8b12c0b0a14182aecab460936b4ed0f9570c9c58e8a45c4954116" + }, + { + "path": "skills/prd-generator/references/prd_template.md", + "sha256": "b4406dae888d9f5c30a321dc685ae74450dc7e33d8d1bded406292250b8b6af1" + }, + { + "path": "skills/prd-generator/references/user_story_examples.md", + "sha256": "bb135dfcce969426c24d570f9be2e3b9b31687ba01db74d5c6231aff1c28b980" + }, + { + "path": "skills/prd-generator/scripts/generate_prd.sh", + "sha256": "9c768a7fcc22fe035e7ba52bb2da2f6de2dda844ccbe0c45bc9cac757021e782" + }, + { + "path": "skills/prd-generator/scripts/validate_prd.sh", + "sha256": "f412de5fa451211797e471f61fe5eddfabc82a6020dc8df0e122fe43f848a74f" + } + ], + "dirSha256": "a2b2e93155c9780557e5195cd862fdda6a084013b56d27e8e4876d751e7ff8f2" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/prd-generator/SKILL.md b/skills/prd-generator/SKILL.md new file mode 100644 index 0000000..bc53f1b --- /dev/null +++ b/skills/prd-generator/SKILL.md @@ -0,0 +1,476 @@ +--- +name: prd-generator +description: Generate comprehensive Product Requirements Documents (PRDs) for product managers. Use this skill when users ask to "create a PRD", "write product requirements", "document a feature", or need help structuring product specifications. +--- + +# PRD Generator + +## Overview + +Generate comprehensive, well-structured Product Requirements Documents (PRDs) that follow industry best practices. This skill helps product managers create clear, actionable requirements documents that align stakeholders and guide development teams. + +## Core Workflow + +When a user requests to create a PRD (e.g., "create a PRD for a user authentication feature"), follow this workflow: + +### Step 1: Gather Context + +Before generating the PRD, collect essential information through a discovery conversation: + +**Required Information:** +- **Feature/Product Name**: What are we building? +- **Problem Statement**: What problem does this solve? +- **Target Users**: Who is this for? +- **Business Goals**: What are we trying to achieve? +- **Success Metrics**: How will we measure success? +- **Timeline/Constraints**: Any deadlines or limitations? + +**Discovery Questions to Ask:** + +``` +1. What problem are you trying to solve? +2. Who is the primary user/audience for this feature? +3. What are the key business objectives? +4. Are there any technical constraints we should be aware of? +5. What does success look like? How will you measure it? +6. What's the timeline for this feature? +7. What's explicitly out of scope? +``` + +**Note:** If the user provides a detailed brief or requirements upfront, you can skip some questions. Always ask for clarification on missing critical information. + +### Step 2: Generate PRD Structure + +Use the standard PRD template from `references/prd_template.md` to create a well-structured document. The PRD should include: + +1. **Executive Summary** - High-level overview (2-3 paragraphs) +2. **Problem Statement** - Clear articulation of the problem +3. **Goals & Objectives** - What we're trying to achieve +4. **User Personas** - Who we're building for +5. **User Stories & Requirements** - Detailed functional requirements +6. **Success Metrics** - KPIs and measurement criteria +7. **Scope** - What's in and out of scope +8. **Technical Considerations** - Architecture, dependencies, constraints +9. **Design & UX Requirements** - UI/UX considerations +10. **Timeline & Milestones** - Key dates and phases +11. **Risks & Mitigation** - Potential issues and solutions +12. **Dependencies & Assumptions** - What we're relying on +13. **Open Questions** - Unresolved items + +### Step 3: Create User Stories + +For each major requirement, generate user stories using the standard format: + +``` +As a [user type], +I want to [action], +So that [benefit/value]. + +Acceptance Criteria: +- [Specific, testable criterion 1] +- [Specific, testable criterion 2] +- [Specific, testable criterion 3] +``` + +Reference `references/user_story_examples.md` for common patterns and best practices. + +### Step 4: Define Success Metrics + +Use appropriate metrics frameworks based on the product type: + +- **AARRR (Pirate Metrics)**: Acquisition, Activation, Retention, Revenue, Referral +- **HEART Framework**: Happiness, Engagement, Adoption, Retention, Task Success +- **North Star Metric**: Single key metric that represents core value +- **OKRs**: Objectives and Key Results + +Consult `references/metrics_frameworks.md` for detailed guidance on each framework. + +### Step 5: Validate & Review + +Optionally run the validation script to ensure PRD completeness: + +```bash +scripts/validate_prd.sh +``` + +This checks for: +- All required sections present +- User stories follow proper format +- Success metrics are defined +- Scope is clearly articulated +- No placeholder text remains + +## Usage Patterns + +### Pattern 1: New Feature PRD + +**User Request:** "Create a PRD for adding dark mode to our mobile app" + +**Execution:** + +1. Ask discovery questions about dark mode requirements +2. Generate PRD using template +3. Create user stories for: + - Theme switching + - Preference persistence + - System-level sync + - Design token updates +4. Define success metrics (adoption rate, user satisfaction) +5. Identify technical dependencies (design system, platform APIs) + +### Pattern 2: Product Enhancement PRD + +**User Request:** "Write requirements for improving our search functionality" + +**Execution:** + +1. Gather context on current search limitations +2. Identify user pain points and desired improvements +3. Generate PRD with focus on: + - Current state analysis + - Proposed enhancements + - Impact assessment +4. Create prioritized user stories +5. Define before/after metrics + +### Pattern 3: New Product PRD + +**User Request:** "I need a PRD for a new analytics dashboard product" + +**Execution:** + +1. Comprehensive discovery (market analysis, user research) +2. Generate full PRD with: + - Market opportunity + - Competitive analysis + - Product vision + - MVP scope + - Go-to-market considerations +3. Detailed user stories for core features +4. Phased rollout plan +5. Success metrics aligned with business goals + +### Pattern 4: Quick PRD / One-Pager + +**User Request:** "Create a lightweight PRD for a small bug fix feature" + +**Execution:** + +1. Generate simplified PRD focusing on: + - Problem statement + - Solution approach + - Acceptance criteria + - Success metrics +2. Skip sections not relevant for small scope +3. Keep document concise (1-2 pages) + +## PRD Best Practices + +### Writing Quality Requirements + +**Good Requirements Are:** +- **Specific**: Clear and unambiguous +- **Measurable**: Can be verified/tested +- **Achievable**: Technically feasible +- **Relevant**: Tied to user/business value +- **Time-bound**: Has clear timeline + +**Avoid:** +- Vague language ("fast", "easy", "intuitive") +- Implementation details (let engineers decide how) +- Feature creep (stick to core requirements) +- Assumptions without validation + +### User Story Best Practices + +**DO:** +- Focus on user value, not features +- Write from user perspective +- Include clear acceptance criteria +- Keep stories independent and small +- Use consistent format + +**DON'T:** +- Write technical implementation details +- Create dependencies between stories +- Make stories too large (epics) +- Use internal jargon +- Skip acceptance criteria + +### Scope Management + +**In-Scope Section:** +- List specific features/capabilities included +- Be explicit and detailed +- Link to user stories + +**Out-of-Scope Section:** +- Explicitly state what's NOT included +- Prevents scope creep +- Manages stakeholder expectations +- Can include "future considerations" + +### Success Metrics Guidelines + +**Choose Metrics That:** +- Align with business objectives +- Are measurable and trackable +- Have clear targets/thresholds +- Include both leading and lagging indicators +- Consider user and business value + +**Typical Metric Categories:** +- **Adoption**: How many users use the feature? +- **Engagement**: How often do they use it? +- **Satisfaction**: Do users like it? +- **Performance**: Does it work well? +- **Business Impact**: Does it drive business goals? + +## Advanced Features + +### PRD Templates for Different Contexts + +The skill supports different PRD formats: + +**Standard PRD** - Full comprehensive document +**Lean PRD** - Streamlined for agile teams +**One-Pager** - Executive summary format +**Technical PRD** - Engineering-focused requirements +**Design PRD** - UX/UI-focused requirements + +Specify the format when requesting: "Create a lean PRD for..." or "Generate a technical PRD for..." + +### Integration with Design + +**Design Requirements Section Should Include:** +- Visual design requirements +- Interaction patterns +- Accessibility requirements (WCAG compliance) +- Responsive design considerations +- Design system components to use +- User flow diagrams +- Wireframe/mockup references + +### Technical Considerations Section + +**Should Address:** +- **Architecture**: High-level technical approach +- **Dependencies**: External services, libraries, APIs +- **Security**: Authentication, authorization, data protection +- **Performance**: Load times, scalability requirements +- **Compatibility**: Browser, device, platform support +- **Data**: Storage, migration, privacy considerations +- **Integration**: How it fits with existing systems + +### Stakeholder Alignment + +**PRD Should Help:** +- Align cross-functional teams +- Set clear expectations +- Enable parallel work streams +- Facilitate decision-making +- Provide single source of truth + +**Distribution Checklist:** +- [ ] Engineering reviewed technical feasibility +- [ ] Design reviewed UX requirements +- [ ] Product leadership approved scope +- [ ] Stakeholders understand timeline +- [ ] Success metrics agreed upon + +## Common PRD Scenarios + +### Scenario 1: Feature Request from Customer + +When creating a PRD based on customer feedback: + +1. Document the customer request verbatim +2. Analyze the underlying problem +3. Generalize the solution for all users +4. Validate with product strategy +5. Scope appropriately (might be smaller or larger than request) + +### Scenario 2: Strategic Initiative + +When creating a PRD for a strategic company initiative: + +1. Link to company OKRs/goals +2. Include market analysis +3. Consider competitive landscape +4. Think multi-phase rollout +5. Include success criteria aligned with strategy + +### Scenario 3: Technical Debt / Infrastructure + +When creating a PRD for technical improvements: + +1. Explain user impact (even if indirect) +2. Document current limitations +3. Articulate benefits (speed, reliability, maintainability) +4. Include engineering input heavily +5. Define measurable improvements + +### Scenario 4: Compliance / Regulatory + +When creating a PRD for compliance requirements: + +1. Reference specific regulations (GDPR, HIPAA, etc.) +2. Include legal/compliance review +3. Deadline is usually non-negotiable +4. Focus on minimum viable compliance +5. Document audit trail requirements + +## Validation & Quality Checks + +### Self-Review Checklist + +Before finalizing the PRD, verify: + +- [ ] **Problem is clear**: Anyone can understand what we're solving +- [ ] **Users are identified**: We know who this is for +- [ ] **Success is measurable**: We can determine if it worked +- [ ] **Scope is bounded**: Clear what's in and out +- [ ] **Requirements are testable**: QA can verify completion +- [ ] **Timeline is realistic**: Estimates validated with engineering +- [ ] **Risks are identified**: We've thought through what could go wrong +- [ ] **Stakeholders aligned**: Key people have reviewed and approved + +### Using the Validation Script + +```bash +# Basic validation +scripts/validate_prd.sh my_prd.md + +# Verbose output with suggestions +scripts/validate_prd.sh my_prd.md --verbose + +# Check specific sections only +scripts/validate_prd.sh my_prd.md --sections "user-stories,metrics" +``` + +## Resources + +This skill includes bundled resources: + +### scripts/ + +- **generate_prd.sh** - Interactive PRD generation workflow +- **validate_prd.sh** - Validates PRD completeness and quality + +### references/ + +- **prd_template.md** - Standard PRD template structure +- **user_story_examples.md** - User story patterns and examples +- **metrics_frameworks.md** - Guide to PM metrics (AARRR, HEART, OKRs) + +## Tips for Product Managers + +### Before Writing the PRD + +1. **Do your research**: User interviews, data analysis, competitive analysis +2. **Validate the problem**: Ensure it's worth solving +3. **Check strategic alignment**: Does this fit our roadmap? +4. **Estimate effort**: Rough t-shirt size with engineering +5. **Consider alternatives**: Is this the best solution? + +### During PRD Creation + +1. **Be clear, not clever**: Simple language wins +2. **Show, don't tell**: Use examples, mockups, diagrams +3. **Think edge cases**: What could go wrong? +4. **Prioritize ruthlessly**: What's MVP vs. nice-to-have? +5. **Collaborate early**: Don't work in isolation + +### After PRD Completion + +1. **Review with stakeholders**: Get feedback early +2. **Iterate based on input**: PRDs are living documents +3. **Present, don't just share**: Walk through the PRD +4. **Get formal sign-off**: Ensure commitment +5. **Keep it updated**: Adjust as understanding evolves + +## Examples + +### Example 1: Mobile Feature PRD + +```bash +# User: "Create a PRD for adding biometric authentication to our iOS app" + +# Assistant will: +# 1. Ask discovery questions about security requirements, user personas, existing auth +# 2. Generate PRD covering: +# - Problem: Password friction, security concerns +# - Solution: Face ID / Touch ID integration +# - User stories: Enable biometric, fallback to password, settings management +# - Metrics: Adoption rate, login success rate, support tickets +# - Technical: iOS Keychain, LocalAuthentication framework +# - Risks: Device compatibility, user privacy concerns +# 3. Output formatted markdown PRD +``` + +### Example 2: Web Platform Enhancement + +```bash +# User: "Write requirements for improving our checkout flow conversion" + +# Assistant will: +# 1. Gather data on current conversion rates and drop-off points +# 2. Generate PRD including: +# - Current state analysis with metrics +# - Proposed improvements (guest checkout, saved payment, progress indicator) +# - A/B test plan +# - Success metrics: Conversion rate increase, time to checkout +# - User stories for each improvement +# 3. Include phased rollout approach +``` + +### Example 3: B2B Product PRD + +```bash +# User: "I need a PRD for an admin dashboard for enterprise customers" + +# Assistant will: +# 1. Identify B2B-specific requirements (multi-tenancy, permissions, reporting) +# 2. Generate comprehensive PRD with: +# - Enterprise user personas (admin, manager, analyst) +# - Role-based access control requirements +# - Reporting and analytics needs +# - Integration requirements (SSO, SCIM) +# - Success metrics: Customer adoption, admin efficiency +# 3. Include enterprise-specific considerations (compliance, SLAs) +``` + +## Troubleshooting + +**Issue: PRD is too long/detailed** + +Solution: Create a "Lean PRD" focusing on problem, solution, acceptance criteria, and metrics. Reserve full PRD for major initiatives. + +**Issue: Requirements are too vague** + +Solution: Add specific examples, use concrete numbers, include visual references. Replace "fast" with "loads in under 2 seconds." + +**Issue: Stakeholders not aligned** + +Solution: Share PRD early as draft, incorporate feedback, present in person, get explicit sign-off before development starts. + +**Issue: Scope keeps expanding** + +Solution: Use "Out of Scope" section aggressively, create separate PRDs for future phases, tie scope to timeline constraints. + +**Issue: Engineers say it's not feasible** + +Solution: Involve engineering earlier in process, be flexible on solution approach, focus on problem not implementation. + +## Best Practices Summary + +1. **Start with the problem, not the solution** +2. **Write for your audience** (execs need summary, engineers need details) +3. **Be specific and measurable** (avoid vague language) +4. **Include visuals** (mockups, diagrams, flows) +5. **Define success upfront** (metrics, not features) +6. **Scope aggressively** (MVP mentality) +7. **Collaborate, don't dictate** (get input from all functions) +8. **Keep it updated** (PRD is a living document) +9. **Focus on "why" and "what", not "how"** (let engineers solve "how") +10. **Make it skimmable** (headers, bullets, summaries) diff --git a/skills/prd-generator/references/metrics_frameworks.md b/skills/prd-generator/references/metrics_frameworks.md new file mode 100644 index 0000000..8aef8f5 --- /dev/null +++ b/skills/prd-generator/references/metrics_frameworks.md @@ -0,0 +1,733 @@ +# Product Metrics Frameworks + +A comprehensive guide to choosing and implementing product metrics frameworks for measuring success. + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [AARRR (Pirate Metrics)](#aarrr-pirate-metrics) +3. [HEART Framework](#heart-framework) +4. [North Star Metric](#north-star-metric) +5. [OKRs (Objectives & Key Results)](#okrs-objectives--key-results) +6. [Product-Market Fit Metrics](#product-market-fit-metrics) +7. [Engagement Metrics](#engagement-metrics) +8. [Choosing the Right Framework](#choosing-the-right-framework) + +--- + +## Overview + +### Why Metrics Matter + +**Metrics help you:** +- Measure feature success objectively +- Make data-driven decisions +- Align teams around shared goals +- Identify what's working and what's not +- Communicate impact to stakeholders + +### Types of Metrics + +**Leading Indicators:** Predict future outcomes +- Example: Free trial sign-ups → Future revenue + +**Lagging Indicators:** Measure past results +- Example: Monthly revenue, churn rate + +**Actionable vs. Vanity Metrics** +- **Actionable:** Can influence through product changes (e.g., conversion rate) +- **Vanity:** Looks good but doesn't drive decisions (e.g., total registered users) + +--- + +## AARRR (Pirate Metrics) + +Created by Dave McClure, this framework focuses on the customer lifecycle. + +### The Five Stages + +``` +Acquisition → Activation → Retention → Revenue → Referral +``` + +### 1. Acquisition + +**What:** How do users find you? + +**Key Metrics:** +- Website traffic +- App store impressions +- Click-through rate (CTR) from ads +- Cost per acquisition (CPA) +- Traffic sources (organic, paid, referral) + +**Example Targets:** +- 10,000 monthly website visitors +- CAC < $50 +- 5% CTR on paid ads + +**Questions to Answer:** +- Which channels drive the most users? +- What's our cost per channel? +- Which campaigns convert best? + +--- + +### 2. Activation + +**What:** Do users have a great first experience? + +**Key Metrics:** +- Sign-up completion rate +- Time to "aha moment" +- Percentage reaching key milestone +- Onboarding completion rate +- Feature adoption in first session + +**Example Targets:** +- 60% sign-up completion +- 40% reach "aha moment" in first session +- 80% complete onboarding + +**Questions to Answer:** +- What does a great first experience look like? +- Where do users drop off in onboarding? +- How quickly do users find value? + +**Example "Aha Moments":** +- **Slack:** Send your first message +- **Dropbox:** Upload your first file +- **Airbnb:** Complete your first booking + +--- + +### 3. Retention + +**What:** Do users come back? + +**Key Metrics:** +- Daily/Weekly/Monthly Active Users (DAU/WAU/MAU) +- Retention curves (Day 1, Day 7, Day 30) +- Churn rate +- Session frequency +- Feature usage over time + +**Example Targets:** +- 40% Day 7 retention +- 25% Day 30 retention +- < 5% monthly churn + +**Cohort Analysis:** +``` +| Cohort | Week 1 | Week 2 | Week 3 | Week 4 | +|-----------|--------|--------|--------|--------| +| Jan 2024 | 100% | 45% | 30% | 25% | +| Feb 2024 | 100% | 50% | 35% | 28% | +``` + +**Questions to Answer:** +- What makes users come back? +- When do users churn? +- How can we re-engage inactive users? + +--- + +### 4. Revenue + +**What:** How do you monetize? + +**Key Metrics:** +- Monthly Recurring Revenue (MRR) +- Average Revenue Per User (ARPU) +- Customer Lifetime Value (LTV) +- Conversion to paid rate +- Upsell/cross-sell rate + +**Example Targets:** +- 5% free-to-paid conversion +- $50 ARPU +- LTV:CAC ratio > 3:1 + +**Formulas:** +``` +LTV = ARPU × Average Customer Lifespan +LTV:CAC = Lifetime Value ÷ Customer Acquisition Cost +Churn Rate = Customers Lost ÷ Total Customers × 100 +``` + +**Questions to Answer:** +- Which features drive conversions? +- What's our payback period? +- How can we increase ARPU? + +--- + +### 5. Referral + +**What:** Do users tell others? + +**Key Metrics:** +- Viral coefficient (K-factor) +- Net Promoter Score (NPS) +- Referral rate +- Social shares +- Word-of-mouth attribution + +**Example Targets:** +- 15% of users refer others +- NPS > 50 +- K-factor > 1 (viral growth) + +**Formulas:** +``` +K-factor = (Number of Invites per User) × (Conversion Rate of Invites) +NPS = % Promoters - % Detractors +``` + +**Questions to Answer:** +- Why do users refer others? +- How can we incentivize referrals? +- What makes us shareable? + +--- + +### AARRR Example: SaaS Product + +| Stage | Metric | Current | Target | Actions | +|-------|--------|---------|--------|---------| +| Acquisition | Monthly visitors | 50,000 | 75,000 | SEO, content marketing | +| Activation | Trial sign-ups | 5% | 8% | Improve landing page | +| Retention | Day 30 retention | 20% | 30% | Onboarding improvements | +| Revenue | Free-to-paid conversion | 3% | 5% | Pricing page redesign | +| Referral | Users who refer | 8% | 15% | Referral program launch | + +--- + +## HEART Framework + +Created by Google, focuses on user experience quality. + +### The Five Dimensions + +**HEART = Happiness + Engagement + Adoption + Retention + Task Success** + +--- + +### 1. Happiness + +**What:** User satisfaction and perception + +**Metrics:** +- Net Promoter Score (NPS) +- Customer Satisfaction (CSAT) +- User ratings/reviews +- Support ticket sentiment +- User feedback scores + +**Measurement Methods:** +- Surveys (post-interaction, periodic) +- App store ratings +- In-app feedback forms +- Social media sentiment + +**Example:** +``` +Feature: New checkout flow +Happiness Metric: CSAT score +Target: > 4.5/5 average rating +Measurement: Post-purchase survey +``` + +--- + +### 2. Engagement + +**What:** Level of user involvement + +**Metrics:** +- Session duration +- Pages/screens per session +- Feature usage frequency +- Time spent in app +- Actions per session + +**Example:** +``` +Feature: News feed +Engagement Metric: Daily sessions per user +Current: 1.2 sessions/day +Target: 2.0 sessions/day +``` + +--- + +### 3. Adoption + +**What:** New users or feature uptake + +**Metrics:** +- New user sign-ups +- Feature adoption rate +- Time to first use +- Percentage of users trying new feature + +**Example:** +``` +Feature: Dark mode +Adoption Metric: % of users enabling dark mode +Target: 40% within 30 days of launch +``` + +--- + +### 4. Retention + +**What:** Users returning over time + +**Metrics:** +- DAU/WAU/MAU +- Retention curves +- Churn rate +- Repeat usage rate + +**Example:** +``` +Feature: Collaboration tools +Retention Metric: Week-over-week active teams +Target: 70% of teams active weekly +``` + +--- + +### 5. Task Success + +**What:** Can users accomplish their goals? + +**Metrics:** +- Task completion rate +- Error rate +- Time to complete task +- Search success rate + +**Example:** +``` +Feature: File upload +Task Success Metric: Upload completion rate +Current: 85% +Target: 95% +Error analysis: Large file timeouts +``` + +--- + +### HEART Framework Template + +| Dimension | Goals | Signals | Metrics | +|-----------|-------|---------|---------| +| **Happiness** | Users love the feature | Positive feedback | NPS > 40 | +| **Engagement** | Users interact frequently | Daily active usage | 60% DAU/MAU | +| **Adoption** | Most users try it | Feature activation | 70% adoption | +| **Retention** | Users keep coming back | Weekly return rate | 50% W1 retention | +| **Task Success** | Users complete goals | Low error rate | 95% success rate | + +--- + +## North Star Metric + +A single metric that best captures the core value you deliver to customers. + +### Characteristics of a Good North Star Metric + +1. **Reflects value delivery** to customers +2. **Measures progress** toward your vision +3. **Actionable** by the team +4. **Leading indicator** of revenue +5. **Understandable** by everyone + +--- + +### Examples by Company + +| Company | North Star Metric | Why | +|---------|------------------|-----| +| **Airbnb** | Nights booked | Core value: successful stays | +| **Spotify** | Time spent listening | Core value: music enjoyment | +| **Slack** | Messages sent by teams | Core value: communication | +| **Facebook** | Daily Active Users | Core value: social connection | +| **Netflix** | Hours watched | Core value: entertainment | +| **Uber** | Rides completed | Core value: transportation | +| **Medium** | Total time reading | Core value: quality content | + +--- + +### Finding Your North Star Metric + +**Step 1: Define your value proposition** +- What core value do you deliver? +- What's the "aha moment" for users? + +**Step 2: Identify the metric** +- What measurement best captures that value? +- Is it a leading indicator of business success? + +**Step 3: Validate the metric** +- Does it correlate with revenue? +- Can teams influence it? +- Is it understandable? + +**Step 4: Set targets and track** +- What's the current baseline? +- What's the target growth rate? +- How will you measure progress? + +--- + +### North Star Metric Tree + +Break down your North Star into contributing metrics: + +``` +North Star: Weekly Active Users + ├── New User Acquisition + │ ├── Sign-ups + │ └── Onboarding completion + ├── Activation + │ └── Users reaching "aha moment" + └── Retention + ├── Week 1 retention + └── Week 4 retention +``` + +--- + +## OKRs (Objectives & Key Results) + +Goal-setting framework popularized by Google. + +### Structure + +**Objective:** Qualitative, inspirational goal +**Key Results:** Quantitative, measurable outcomes (3-5 per objective) + +--- + +### Writing Good OKRs + +**Objective Characteristics:** +- Inspirational and motivating +- Qualitative +- Time-bound (quarterly or annual) +- Aligned with company strategy + +**Key Result Characteristics:** +- Quantitative and measurable +- Specific with clear targets +- Ambitious but achievable +- 3-5 per objective + +--- + +### Examples + +#### Example 1: Growth OKR + +**Objective:** Become the go-to platform for small business invoicing + +**Key Results:** +1. Increase monthly active businesses from 10,000 to 25,000 +2. Achieve 40% month-over-month retention +3. Reach NPS of 50+ +4. Generate $500K MRR + +--- + +#### Example 2: Product Quality OKR + +**Objective:** Deliver a world-class mobile experience + +**Key Results:** +1. Reduce app crash rate from 2.5% to <0.5% +2. Achieve 4.5+ star rating on both app stores +3. Improve app load time to <2 seconds (p95) +4. Increase mobile DAU/MAU ratio from 30% to 45% + +--- + +#### Example 3: Feature Launch OKR + +**Objective:** Successfully launch team collaboration features + +**Key Results:** +1. 60% of active users try collaboration features within 30 days +2. 25% of users become weekly active collaborators +3. Collaboration features drive 15% increase in paid conversions +4. Achieve CSAT score of 4.2/5 for collaboration features + +--- + +### OKR Template for PRDs + +```markdown +## OKRs + +### Objective: [Inspirational goal] + +**Key Results:** +1. [Metric 1]: Increase/decrease [current] to [target] by [date] +2. [Metric 2]: Achieve [target value] for [metric] +3. [Metric 3]: [Specific measurable outcome] + +**Tracking:** +- Current status: [Progress report] +- Dashboard: [Link to metrics dashboard] +- Review cadence: [Weekly/bi-weekly] +``` + +--- + +## Product-Market Fit Metrics + +Measuring whether you've achieved product-market fit. + +### Sean Ellis Test + +Survey question: **"How would you feel if you could no longer use [product]?"** + +- Very disappointed +- Somewhat disappointed +- Not disappointed + +**PMF Threshold:** 40%+ answer "Very disappointed" + +--- + +### Other PMF Indicators + +**Qualitative Signals:** +- Users voluntarily refer others +- Organic growth without marketing +- High engagement and retention +- Users find creative use cases +- Positive unsolicited feedback + +**Quantitative Metrics:** +- **Retention:** 40%+ month 1 retention +- **NPS:** Score > 50 +- **Growth:** 10%+ month-over-month organic growth +- **Engagement:** High DAU/MAU ratio (>40%) +- **LTV:CAC:** Ratio > 3:1 + +--- + +## Engagement Metrics + +Deep dive into measuring user engagement. + +### DAU/WAU/MAU + +**Definitions:** +- **DAU:** Daily Active Users (unique users in a day) +- **WAU:** Weekly Active Users (unique users in a week) +- **MAU:** Monthly Active Users (unique users in a month) + +**Ratios:** +- **DAU/MAU:** Stickiness (how many monthly users come daily) +- **DAU/WAU:** Daily engagement intensity + +**Benchmarks:** +- **Excellent:** DAU/MAU > 50% (e.g., messaging apps) +- **Good:** DAU/MAU = 20-50% (e.g., social media) +- **Average:** DAU/MAU = 10-20% (e.g., utilities) + +--- + +### Session Metrics + +**Key Measurements:** +- **Session duration:** Time spent per session +- **Session frequency:** Sessions per user per day/week +- **Session depth:** Actions/pages per session + +**Example Targets:** +- Session duration: > 5 minutes +- Session frequency: 2+ sessions/day +- Session depth: > 8 page views + +--- + +### Feature Engagement + +**Metrics:** +- **Adoption rate:** % of users who try the feature +- **Active usage:** % of users actively using regularly +- **Depth of use:** Actions per user within feature + +**Example:** +``` +Feature: Document collaboration +- Adoption: 50% of users have collaborated at least once +- Active usage: 30% collaborate weekly +- Depth: Average 12 collaborative edits per week +``` + +--- + +## Choosing the Right Framework + +### Decision Matrix + +| Framework | Best For | Time Horizon | Complexity | +|-----------|----------|--------------|------------| +| **AARRR** | Growth-focused products, startups | Ongoing | Medium | +| **HEART** | UX quality, feature launches | Per feature | Low-Medium | +| **North Star** | Company alignment, focus | Ongoing | Low | +| **OKRs** | Goal setting, team alignment | Quarterly | Medium-High | + +--- + +### By Product Stage + +**Early Stage (Pre-PMF):** +- Focus: Product-Market Fit metrics +- Framework: AARRR (Activation & Retention focus) +- North Star: Early engagement metric + +**Growth Stage (Post-PMF):** +- Focus: Scaling user acquisition +- Framework: Full AARRR funnel +- North Star: Growth-oriented metric + +**Mature Stage:** +- Focus: Optimization and expansion +- Framework: HEART for features, OKRs for goals +- North Star: Revenue or engagement metric + +--- + +### By Product Type + +**Consumer Apps:** +- AARRR for growth funnel +- DAU/MAU for engagement +- Viral coefficient for referral + +**B2B SaaS:** +- ARR/MRR for revenue +- Churn rate for retention +- Expansion revenue for growth + +**Marketplace:** +- GMV (Gross Merchandise Value) +- Take rate (% of transaction) +- Liquidity (supply/demand balance) + +**Content Platforms:** +- Time spent on platform +- Content creation rate +- Content consumption rate + +--- + +## Metrics Anti-Patterns + +### Common Mistakes + +**1. Too Many Metrics** +- **Problem:** Tracking everything = focusing on nothing +- **Solution:** Choose 3-5 key metrics per initiative + +**2. Vanity Metrics** +- **Problem:** Total users looks good but doesn't inform decisions +- **Solution:** Focus on active users, engagement, retention + +**3. Lagging Only** +- **Problem:** Only tracking revenue = rear-view mirror +- **Solution:** Balance with leading indicators (activation, engagement) + +**4. No Targets** +- **Problem:** Tracking without goals +- **Solution:** Set specific, time-bound targets + +**5. Not Segmenting** +- **Problem:** Average metrics hide important patterns +- **Solution:** Segment by user type, cohort, feature usage + +--- + +## Metrics Template for PRDs + +```markdown +## Success Metrics + +### North Star Metric +**Metric:** [Your single most important metric] +**Current:** [Baseline value] +**Target:** [Goal value by launch + X months] +**Why:** [Why this metric matters] + +### Supporting Metrics + +#### Acquisition +- **Metric 1:** [Name] - Current: [X], Target: [Y] +- **Metric 2:** [Name] - Current: [X], Target: [Y] + +#### Activation +- **Metric 1:** [Name] - Current: [X], Target: [Y] +- **Metric 2:** [Name] - Current: [X], Target: [Y] + +#### Retention +- **Metric 1:** [Name] - Current: [X], Target: [Y] +- **Metric 2:** [Name] - Current: [X], Target: [Y] + +#### Revenue (if applicable) +- **Metric 1:** [Name] - Current: [X], Target: [Y] + +### Counter-Metrics +[Metrics to ensure you're not sacrificing other areas] +- Example: Ensure support tickets don't increase > 10% + +### Measurement Plan +- **Dashboard:** [Link] +- **Review Cadence:** [Weekly/bi-weekly] +- **Owner:** [Name] +``` + +--- + +## Resources & Tools + +### Analytics Platforms +- **Amplitude:** Product analytics, retention analysis +- **Mixpanel:** Event tracking, funnel analysis +- **Google Analytics:** Web analytics +- **Heap:** Auto-capture analytics + +### Survey Tools +- **Delighted:** NPS surveys +- **SurveyMonkey:** Custom surveys +- **Typeform:** Engaging survey forms + +### Dashboard Tools +- **Tableau:** Data visualization +- **Looker:** Business intelligence +- **Datadog:** Infrastructure metrics +- **Metabase:** Open-source BI + +--- + +## Summary + +**Key Takeaways:** + +1. **Choose frameworks** that match your product stage and goals +2. **Balance leading and lagging** indicators +3. **Set specific targets** with timelines +4. **Track counter-metrics** to avoid unintended consequences +5. **Review regularly** and iterate on what you measure +6. **Keep it simple** - 3-5 key metrics per initiative +7. **Align metrics** with business objectives +8. **Make metrics actionable** - can the team influence them? + +**Remember:** The best metric is one that drives the right behavior and aligns your team around what matters most to users and the business. diff --git a/skills/prd-generator/references/prd_template.md b/skills/prd-generator/references/prd_template.md new file mode 100644 index 0000000..9eee869 --- /dev/null +++ b/skills/prd-generator/references/prd_template.md @@ -0,0 +1,572 @@ +# Product Requirements Document Template + +This template provides a comprehensive structure for creating Product Requirements Documents (PRDs). Adapt sections based on your needs and project scope. + +--- + +## Document Header + +**Product/Feature Name:** [Name] +**Status:** [Draft | In Review | Approved] +**Author:** [Your Name] +**Stakeholders:** [List key stakeholders] +**Date Created:** [YYYY-MM-DD] +**Last Updated:** [YYYY-MM-DD] +**Version:** [1.0] + +--- + +## Executive Summary + +**One-liner:** [Single sentence describing the product/feature] + +**Overview:** [2-3 paragraph summary of what you're building, why, and expected impact] + +**Quick Facts:** +- **Target Users:** [Primary user segment] +- **Problem Solved:** [Core problem being addressed] +- **Key Metric:** [Primary success metric] +- **Target Launch:** [Date or Quarter] + +--- + +## Table of Contents + +1. [Problem Statement](#problem-statement) +2. [Goals & Objectives](#goals--objectives) +3. [User Personas](#user-personas) +4. [User Stories & Requirements](#user-stories--requirements) +5. [Success Metrics](#success-metrics) +6. [Scope](#scope) +7. [Technical Considerations](#technical-considerations) +8. [Design & UX Requirements](#design--ux-requirements) +9. [Timeline & Milestones](#timeline--milestones) +10. [Risks & Mitigation](#risks--mitigation) +11. [Dependencies & Assumptions](#dependencies--assumptions) +12. [Open Questions](#open-questions) +13. [Stakeholder Sign-Off](#stakeholder-sign-off) + +--- + +## Problem Statement + +### The Problem + +[Clearly articulate the problem you're solving. What pain point exists today?] + +### Current State + +[Describe how users currently handle this problem, including workarounds] + +### Impact + +**User Impact:** +- [How this affects users] +- [Quantify if possible: "Users spend 30 minutes daily on workarounds"] + +**Business Impact:** +- [How this affects the business] +- [Include metrics: "Costs us $X in support tickets monthly"] + +### Why Now? + +[Explain the urgency or strategic importance of solving this now] + +--- + +## Goals & Objectives + +### Business Goals + +1. **[Goal 1]:** [Description and expected impact] +2. **[Goal 2]:** [Description and expected impact] +3. **[Goal 3]:** [Description and expected impact] + +### User Goals + +1. **[Goal 1]:** [What users want to achieve] +2. **[Goal 2]:** [What users want to achieve] +3. **[Goal 3]:** [What users want to achieve] + +### Non-Goals + +[What we're explicitly NOT trying to achieve with this effort] + +--- + +## User Personas + +### Primary Persona: [Name/Type] + +**Demographics:** +- Age range: [Range] +- Role/Title: [Role] +- Tech savviness: [Low/Medium/High] +- Location: [Geographic info if relevant] + +**Behaviors:** +- [Key behavior pattern 1] +- [Key behavior pattern 2] +- [Key behavior pattern 3] + +**Needs & Motivations:** +- [What they need to accomplish] +- [What drives their decision-making] + +**Pain Points:** +- [Current frustration 1] +- [Current frustration 2] +- [Current frustration 3] + +**Quote:** _"[Verbatim user quote that captures their perspective]"_ + +### Secondary Persona: [Name/Type] + +[Repeat structure as needed for additional personas] + +--- + +## User Stories & Requirements + +### Epic: [Epic Name] + +#### Must-Have Stories (P0) + +##### Story 1: [Feature Name] + +**User Story:** +``` +As a [user type], +I want to [perform action], +So that [achieve benefit/value]. +``` + +**Acceptance Criteria:** +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Edge case: [Specific scenario] + +**Priority:** Must Have (P0) +**Effort:** [T-shirt size: XS/S/M/L/XL] +**Dependencies:** [List any dependencies] + +--- + +##### Story 2: [Feature Name] + +[Repeat structure] + +--- + +#### Should-Have Stories (P1) + +[List P1 stories using same format] + +--- + +#### Nice-to-Have Stories (P2) + +[List P2 stories using same format] + +--- + +### Functional Requirements + +| Req ID | Description | Priority | Status | +|--------|-------------|----------|--------| +| FR-001 | [Requirement description] | Must Have | Open | +| FR-002 | [Requirement description] | Should Have | Open | +| FR-003 | [Requirement description] | Nice to Have | Open | + +### Non-Functional Requirements + +| Req ID | Category | Description | Target | +|--------|----------|-------------|--------| +| NFR-001 | Performance | Page load time | < 2 seconds | +| NFR-002 | Availability | Uptime SLA | 99.9% | +| NFR-003 | Security | Data encryption | AES-256 | +| NFR-004 | Accessibility | WCAG compliance | Level AA | + +--- + +## Success Metrics + +### Key Performance Indicators (KPIs) + +#### Primary Metric (North Star) + +**Metric:** [Your North Star Metric] +**Definition:** [How it's calculated] +**Current Baseline:** [Current value] +**Target:** [Target value by launch + X months] +**Why This Metric:** [Why this measures success] + +#### Secondary Metrics + +| Metric | Current | Target | Timeframe | +|--------|---------|--------|-----------| +| [Metric 1] | [Value] | [Value] | [When] | +| [Metric 2] | [Value] | [Value] | [When] | +| [Metric 3] | [Value] | [Value] | [When] | + +### Measurement Framework + +**Framework Used:** [AARRR / HEART / Custom] + +**Acquisition:** +- [Metric and target] + +**Activation:** +- [Metric and target] + +**Retention:** +- [Metric and target] + +**Revenue:** +- [Metric and target] + +**Referral:** +- [Metric and target] + +### Analytics Implementation + +**Events to Track:** +- `[event_name_1]` - [When triggered] +- `[event_name_2]` - [When triggered] +- `[event_name_3]` - [When triggered] + +**Dashboards:** +- [Link to primary dashboard] +- [Link to secondary dashboard] + +--- + +## Scope + +### In Scope + +**Phase 1 (MVP):** +- [Feature/capability 1] +- [Feature/capability 2] +- [Feature/capability 3] + +**Phase 2 (Post-MVP):** +- [Feature/capability 1] +- [Feature/capability 2] + +### Out of Scope + +**Explicitly Excluded:** +- [Item 1 and why it's excluded] +- [Item 2 and why it's excluded] +- [Item 3 and why it's excluded] + +### Future Considerations + +**Potential Future Enhancements:** +- [Enhancement 1] +- [Enhancement 2] +- [Enhancement 3] + +--- + +## Technical Considerations + +### High-Level Architecture + +[Describe the technical approach, architecture diagram link, or key architectural decisions] + +### Technology Stack + +**Frontend:** +- [Framework/library] +- [Key dependencies] + +**Backend:** +- [Language/framework] +- [Key services] + +**Infrastructure:** +- [Hosting platform] +- [Database] +- [Caching layer] + +### API Requirements + +**New Endpoints:** +- `GET /api/v1/[endpoint]` - [Description] +- `POST /api/v1/[endpoint]` - [Description] +- `PUT /api/v1/[endpoint]` - [Description] + +**External APIs:** +- [Third-party API 1] +- [Third-party API 2] + +### Security Requirements + +- **Authentication:** [Method: JWT, OAuth, etc.] +- **Authorization:** [RBAC, ABAC, etc.] +- **Data Encryption:** [At rest and in transit] +- **Compliance:** [GDPR, HIPAA, SOC 2, etc.] +- **Rate Limiting:** [Limits and throttling strategy] + +### Performance Requirements + +- **Response Time:** [Target: e.g., < 200ms p95] +- **Throughput:** [Requests per second] +- **Concurrency:** [Concurrent users supported] +- **Database:** [Query performance targets] +- **Caching:** [Cache hit rate targets] + +### Scalability + +- **Expected Load:** [Users, requests, data volume] +- **Growth Projections:** [12-month forecast] +- **Scaling Strategy:** [Horizontal/vertical, auto-scaling] + +### Data Considerations + +**Data Model:** +- [Key entities and relationships] + +**Storage Requirements:** +- [Estimated storage needs] +- [Retention policies] + +**Data Migration:** +- [Migration plan if updating existing data] +- [Rollback strategy] + +**Privacy & Compliance:** +- PII handling: [How personal data is handled] +- Data deletion: [User data deletion process] +- Audit logging: [What's logged and retained] + +--- + +## Design & UX Requirements + +### User Experience Principles + +[Key UX principles guiding this feature] + +### User Flows + +**Primary Flow:** +1. [Step 1] +2. [Step 2] +3. [Step 3] +4. [Final state] + +**Alternative Flows:** +- [Alternative scenario 1] +- [Error handling flow] + +### Visual Design + +**Design Assets:** +- [Link to Figma/Sketch files] +- [Link to design system] + +**Key Screens:** +- [Screen 1]: [Link to mockup] +- [Screen 2]: [Link to mockup] +- [Screen 3]: [Link to mockup] + +**Design System Components:** +- [Component 1 from design system] +- [Component 2 from design system] +- [New components needed] + +### Interaction Patterns + +- [Pattern 1: e.g., "Click to expand"] +- [Pattern 2: e.g., "Drag to reorder"] +- [Pattern 3: e.g., "Inline editing"] + +### Accessibility (a11y) + +**Requirements:** +- WCAG 2.1 Level AA compliance +- Keyboard navigation support +- Screen reader compatibility +- Color contrast ratios (4.5:1 for text) +- Focus indicators visible +- Alternative text for images +- Semantic HTML structure + +**Testing:** +- [ ] Keyboard-only navigation test +- [ ] Screen reader test (NVDA/JAWS) +- [ ] Color contrast verification +- [ ] Automated a11y testing (axe/Lighthouse) + +### Responsive Design + +**Breakpoints:** +- Mobile: 320px - 767px +- Tablet: 768px - 1023px +- Desktop: 1024px+ + +**Platform-Specific Considerations:** +- [iOS-specific requirements] +- [Android-specific requirements] +- [Web-specific requirements] + +--- + +## Timeline & Milestones + +**Target Launch Date:** [YYYY-MM-DD or Q#] + +### Phases + +| Phase | Deliverables | Owner | Start Date | End Date | +|-------|-------------|-------|------------|----------| +| **Discovery** | Requirements finalized, design approved | PM/Design | [Date] | [Date] | +| **Design** | High-fidelity mockups, user testing | Design | [Date] | [Date] | +| **Development** | Backend + frontend implementation | Engineering | [Date] | [Date] | +| **QA** | Testing complete, bugs resolved | QA | [Date] | [Date] | +| **Beta** | Beta testing with select users | PM/QA | [Date] | [Date] | +| **Launch** | Production release | Engineering | [Date] | [Date] | +| **Post-Launch** | Monitoring, iteration based on data | PM/Engineering | [Date] | [Date] | + +### Key Milestones + +- **[Date]:** Kickoff meeting +- **[Date]:** Design review +- **[Date]:** Technical design review +- **[Date]:** Development complete +- **[Date]:** QA complete +- **[Date]:** Beta launch +- **[Date]:** General availability +- **[Date]:** Post-launch review + +--- + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation Strategy | Owner | +|------|--------|------------|---------------------|-------| +| [Risk 1: e.g., "API partner delays"] | High | Medium | [Strategy: e.g., "Build with mock data, switch when ready"] | [Name] | +| [Risk 2] | Medium | High | [Strategy] | [Name] | +| [Risk 3] | Low | Low | [Strategy] | [Name] | + +### Contingency Plans + +**If [scenario occurs]:** +- Action plan: [Steps to take] +- Decision maker: [Who makes the call] +- Trigger: [What indicates this scenario] + +--- + +## Dependencies & Assumptions + +### Dependencies + +**Internal:** +- [ ] [Dependency 1: e.g., "Design system update"] +- [ ] [Dependency 2: e.g., "API v2 completion"] +- [ ] [Dependency 3] + +**External:** +- [ ] [Dependency 1: e.g., "Third-party API approval"] +- [ ] [Dependency 2] + +### Assumptions + +- [Assumption 1: e.g., "Users have updated to app version 2.0+"] +- [Assumption 2: e.g., "Budget approved for $X infrastructure costs"] +- [Assumption 3] + +--- + +## Open Questions + +Track unresolved items that need decisions: + +- [ ] **[Question 1]** + - **Context:** [Why this matters] + - **Options:** [List options being considered] + - **Owner:** [Who will decide] + - **Deadline:** [When decision needed] + +- [ ] **[Question 2]** + - **Context:** + - **Options:** + - **Owner:** + - **Deadline:** + +--- + +## Stakeholder Sign-Off + +| Stakeholder | Role | Review Status | Approved | Date | +|------------|------|---------------|----------|------| +| [Name] | Product Lead | ⏳ Pending / ✅ Complete | ☐ | - | +| [Name] | Engineering Lead | ⏳ Pending / ✅ Complete | ☐ | - | +| [Name] | Design Lead | ⏳ Pending / ✅ Complete | ☐ | - | +| [Name] | QA Lead | ⏳ Pending / ✅ Complete | ☐ | - | +| [Name] | Security | ⏳ Pending / ✅ Complete | ☐ | - | +| [Name] | Legal/Compliance | ⏳ Pending / ✅ Complete | ☐ | - | + +--- + +## Appendix + +### References + +- [User research findings link] +- [Competitive analysis link] +- [Market research link] +- [Technical design doc link] + +### Related Documents + +- [Link to design files] +- [Link to API documentation] +- [Link to test plan] + +### Glossary + +- **[Term 1]:** [Definition] +- **[Term 2]:** [Definition] +- **[Term 3]:** [Definition] + +### Change Log + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | [YYYY-MM-DD] | [Name] | Initial draft | +| 1.1 | [YYYY-MM-DD] | [Name] | [Changes made] | + +--- + +## Document Usage Notes + +**When to use this template:** +- Major new features +- New products +- Significant product enhancements +- Cross-functional initiatives + +**When NOT to use this template:** +- Minor bug fixes +- Small UI tweaks +- Maintenance tasks +- Simple A/B tests + +**Customization:** +- Remove sections not relevant to your project +- Add sections specific to your domain +- Adjust detail level based on project scope +- Use "Lean PRD" format for smaller projects + +**Best Practices:** +- Start with problem, not solution +- Keep it concise but complete +- Use specific, measurable language +- Include visual aids (mockups, diagrams) +- Review with all stakeholders +- Keep it updated as understanding evolves diff --git a/skills/prd-generator/references/user_story_examples.md b/skills/prd-generator/references/user_story_examples.md new file mode 100644 index 0000000..94c5ac1 --- /dev/null +++ b/skills/prd-generator/references/user_story_examples.md @@ -0,0 +1,667 @@ +# User Story Examples & Best Practices + +A comprehensive guide to writing effective user stories with real-world examples across different domains. + +--- + +## Table of Contents + +1. [User Story Format](#user-story-format) +2. [Anatomy of Good User Stories](#anatomy-of-good-user-stories) +3. [Examples by Domain](#examples-by-domain) +4. [Acceptance Criteria Patterns](#acceptance-criteria-patterns) +5. [Common Mistakes](#common-mistakes) +6. [Story Splitting](#story-splitting) + +--- + +## User Story Format + +### Standard Template + +``` +As a [user type/persona], +I want to [perform action/use feature], +So that [achieve benefit/value]. +``` + +### Alternative Formats + +**Job Story (Jobs-to-be-Done):** +``` +When [situation], +I want to [motivation], +So I can [expected outcome]. +``` + +**Feature-Driven:** +``` +In order to [receive benefit], +As a [user type], +I want [feature/capability]. +``` + +--- + +## Anatomy of Good User Stories + +### INVEST Criteria + +Good user stories are: + +- **Independent:** Can be developed and delivered separately +- **Negotiable:** Details can be discussed and adjusted +- **Valuable:** Delivers clear value to users or business +- **Estimable:** Can be sized/estimated by the team +- **Small:** Can be completed in one iteration/sprint +- **Testable:** Has clear acceptance criteria + +### Key Components + +1. **User Type:** Who is the user? Be specific. +2. **Action:** What do they want to do? One clear action. +3. **Value:** Why do they want it? The benefit or outcome. +4. **Acceptance Criteria:** How do we know it's done? Testable conditions. + +--- + +## Examples by Domain + +### E-Commerce + +#### Example 1: Product Search + +**User Story:** +``` +As a online shopper, +I want to filter products by price range, +So that I can find items within my budget. +``` + +**Acceptance Criteria:** +- [ ] Given I'm on the product listing page, when I set a minimum and maximum price, then only products within that range are displayed +- [ ] Given I've applied a price filter, when I clear the filter, then all products are shown again +- [ ] Given I set an invalid price range (min > max), when I apply the filter, then I see an error message +- [ ] Price filter persists when I navigate between pages of results +- [ ] Filter displays count of products matching the criteria + +**Priority:** Must Have (P0) +**Story Points:** 5 + +--- + +#### Example 2: Guest Checkout + +**User Story:** +``` +As a first-time customer, +I want to checkout without creating an account, +So that I can complete my purchase quickly. +``` + +**Acceptance Criteria:** +- [ ] Given I have items in cart, when I click checkout, then I see options for "Guest Checkout" and "Sign In" +- [ ] Given I choose guest checkout, when I enter shipping and payment info, then I can complete the order +- [ ] Given I complete a guest checkout, when the order is placed, then I receive a confirmation email +- [ ] After guest checkout, I see an option to create an account with my order information +- [ ] Guest checkout flow takes no more than 3 screens + +**Priority:** Must Have (P0) +**Story Points:** 8 + +--- + +### SaaS / B2B Platform + +#### Example 3: Team Collaboration + +**User Story:** +``` +As a project manager, +I want to assign tasks to team members, +So that everyone knows their responsibilities. +``` + +**Acceptance Criteria:** +- [ ] Given I'm viewing a task, when I click "Assign", then I see a list of team members +- [ ] Given I select a team member, when I confirm the assignment, then they receive a notification +- [ ] Given a task is assigned, when I view the task list, then I can see who is assigned to each task +- [ ] Given I'm a team member, when I'm assigned a task, then it appears in my "My Tasks" view +- [ ] I can assign multiple people to a single task +- [ ] I can change or remove task assignments + +**Priority:** Must Have (P0) +**Story Points:** 5 + +--- + +#### Example 4: Usage Analytics + +**User Story:** +``` +As a SaaS administrator, +I want to view team usage analytics, +So that I can optimize our subscription plan. +``` + +**Acceptance Criteria:** +- [ ] Given I have admin permissions, when I navigate to analytics, then I see usage metrics for the last 30 days +- [ ] Dashboard shows: active users, feature usage, API calls, and storage used +- [ ] Given I select a date range, when I apply the filter, then metrics update accordingly +- [ ] I can export analytics data as CSV +- [ ] Metrics update in real-time (max 5-minute delay) + +**Priority:** Should Have (P1) +**Story Points:** 8 + +--- + +### Mobile App + +#### Example 5: Push Notifications + +**User Story:** +``` +As a mobile app user, +I want to customize which notifications I receive, +So that I only see relevant updates. +``` + +**Acceptance Criteria:** +- [ ] Given I'm in settings, when I navigate to notifications, then I see toggle switches for each notification type +- [ ] Notification types include: messages, mentions, updates, promotions +- [ ] Given I disable a notification type, when that event occurs, then I don't receive a push notification +- [ ] Settings sync across devices using the same account +- [ ] Default settings are: messages ON, mentions ON, updates ON, promotions OFF + +**Priority:** Must Have (P0) +**Story Points:** 5 + +--- + +#### Example 6: Offline Mode + +**User Story:** +``` +As a mobile user with unreliable connectivity, +I want to access my recently viewed content offline, +So that I can continue using the app without internet. +``` + +**Acceptance Criteria:** +- [ ] Given I've viewed content while online, when I go offline, then I can still access the last 50 items viewed +- [ ] Given I'm offline, when I try to access new content, then I see a "No connection" message with cached content +- [ ] Given I'm offline and make changes, when I reconnect, then changes sync automatically +- [ ] Offline indicator appears in the app when connectivity is lost +- [ ] Cached content is automatically cleared after 7 days + +**Priority:** Should Have (P1) +**Story Points:** 13 + +--- + +### Authentication & Security + +#### Example 7: Two-Factor Authentication + +**User Story:** +``` +As a security-conscious user, +I want to enable two-factor authentication, +So that my account is protected from unauthorized access. +``` + +**Acceptance Criteria:** +- [ ] Given I'm in security settings, when I enable 2FA, then I can choose between SMS and authenticator app +- [ ] Given I choose authenticator app, when I scan the QR code, then I must enter a verification code to activate +- [ ] Given 2FA is enabled, when I log in, then I'm prompted for my second factor +- [ ] I receive backup codes when activating 2FA +- [ ] I can disable 2FA with my current password + 2FA code + +**Priority:** Must Have (P0) +**Story Points:** 13 + +--- + +#### Example 8: Password Reset + +**User Story:** +``` +As a user who forgot my password, +I want to reset it via email, +So that I can regain access to my account. +``` + +**Acceptance Criteria:** +- [ ] Given I click "Forgot Password", when I enter my email, then I receive a reset link within 5 minutes +- [ ] Reset link expires after 24 hours +- [ ] Given I click the reset link, when I enter a new password, then it must meet password requirements (shown on screen) +- [ ] After successful reset, I'm logged in automatically +- [ ] If email doesn't exist in system, show generic message (don't reveal if account exists) + +**Priority:** Must Have (P0) +**Story Points:** 5 + +--- + +### Content & Media + +#### Example 9: Video Upload + +**User Story:** +``` +As a content creator, +I want to upload videos with progress tracking, +So that I know when my upload is complete. +``` + +**Acceptance Criteria:** +- [ ] Given I select a video file, when I click upload, then I see a progress bar showing percentage complete +- [ ] Supported formats: MP4, MOV, AVI (max 2GB) +- [ ] Given upload is in progress, when I navigate away, then upload continues in background +- [ ] Given upload completes, when processing is done, then I receive a notification +- [ ] Given upload fails, when error occurs, then I see specific error message and can retry + +**Priority:** Must Have (P0) +**Story Points:** 8 + +--- + +### Admin & Configuration + +#### Example 10: User Permissions + +**User Story:** +``` +As an administrator, +I want to assign role-based permissions to users, +So that team members have appropriate access levels. +``` + +**Acceptance Criteria:** +- [ ] Given I'm viewing a user profile, when I click "Change Role", then I see available roles: Admin, Editor, Viewer +- [ ] Given I assign a role, when I save, then user immediately gains/loses associated permissions +- [ ] Admin: full access; Editor: create/edit content; Viewer: read-only +- [ ] I can create custom roles with specific permission combinations +- [ ] Audit log records all permission changes with timestamp and admin who made the change + +**Priority:** Must Have (P0) +**Story Points:** 13 + +--- + +## Acceptance Criteria Patterns + +### Given-When-Then Format + +Most structured format, excellent for complex logic: + +``` +Given [initial context/state], +When [action/event], +Then [expected outcome]. +``` + +**Example:** +``` +Given I'm a logged-in user with items in my cart, +When I apply a 20% discount code, +Then the cart total is reduced by 20% and displays the discount. +``` + +### Checklist Format + +Simpler, good for straightforward requirements: + +``` +- [ ] Requirement 1 +- [ ] Requirement 2 +- [ ] Edge case handling +``` + +### Table Format + +Great for multiple scenarios: + +| Condition | Action | Expected Result | +|-----------|--------|----------------| +| Valid email | Click "Send" | Confirmation message | +| Invalid email | Click "Send" | Error message | +| Empty field | Click "Send" | "Required field" error | + +--- + +## Common Mistakes to Avoid + +### ❌ Too Technical + +**Bad:** +``` +As a user, +I want the system to use Redis caching with 10-minute TTL, +So that page loads are fast. +``` + +**Good:** +``` +As a user, +I want pages to load in under 2 seconds, +So that I can browse efficiently. +``` + +**Why:** User stories focus on user value, not implementation. Let engineers choose the solution. + +--- + +### ❌ Too Vague + +**Bad:** +``` +As a user, +I want the app to be fast, +So that I have a good experience. +``` + +**Good:** +``` +As a user, +I want search results to appear in under 1 second, +So that I can quickly find what I need. +``` + +**Why:** "Fast" is subjective. Be specific and measurable. + +--- + +### ❌ Missing the "Why" + +**Bad:** +``` +As a user, +I want to upload profile pictures. +``` + +**Good:** +``` +As a user, +I want to upload a profile picture, +So that other users can recognize me in the community. +``` + +**Why:** Understanding the "why" helps the team make better decisions. + +--- + +### ❌ Multiple Actions in One Story + +**Bad:** +``` +As a user, +I want to create an account, set up my profile, and invite team members, +So that I can start using the platform. +``` + +**Good:** Split into three stories: +``` +Story 1: As a user, I want to create an account... +Story 2: As a user, I want to set up my profile... +Story 3: As an account owner, I want to invite team members... +``` + +**Why:** Stories should be small and focused on one capability. + +--- + +### ❌ No Acceptance Criteria + +**Bad:** +``` +As a user, +I want to search for products, +So that I can find what I need. +``` + +**Good:** Add specific criteria: +``` +Acceptance Criteria: +- [ ] Search works on product name and description +- [ ] Results display in under 2 seconds +- [ ] Displays "No results found" when no matches +- [ ] Shows top 20 results with pagination +``` + +**Why:** Acceptance criteria define "done" and enable testing. + +--- + +## Story Splitting Techniques + +When a story is too large, use these techniques to split it: + +### 1. By Workflow Steps + +**Large Story:** +``` +As a user, I want to book a flight online. +``` + +**Split Stories:** +- Search for flights +- Select flight +- Enter passenger details +- Choose seat +- Make payment +- Receive confirmation + +--- + +### 2. By User Persona + +**Large Story:** +``` +As a user, I want to manage my subscriptions. +``` + +**Split Stories:** +- As a free user, I want to view available plans +- As a paid user, I want to upgrade my plan +- As an admin, I want to manage team subscriptions + +--- + +### 3. By Business Rules + +**Large Story:** +``` +As a user, I want to apply discount codes. +``` + +**Split Stories:** +- Apply percentage discount (e.g., 20% off) +- Apply fixed amount discount (e.g., $10 off) +- Apply free shipping discount +- Handle expired discount codes +- Limit one discount per order + +--- + +### 4. By Data Variations + +**Large Story:** +``` +As a user, I want to import contacts. +``` + +**Split Stories:** +- Import from CSV file +- Import from Google Contacts +- Import from Microsoft Outlook +- Import from LinkedIn + +--- + +### 5. By CRUD Operations + +**Large Story:** +``` +As a user, I want to manage my projects. +``` + +**Split Stories:** +- Create a new project +- View project details +- Update project settings +- Delete a project + +--- + +### 6. By Happy Path / Edge Cases + +**MVP Story (Happy Path):** +``` +As a user, I want to upload a profile photo (JPG, < 5MB). +``` + +**Follow-up Stories:** +- Support additional formats (PNG, GIF) +- Handle files larger than 5MB with error message +- Auto-crop/resize images +- Allow photo deletion + +--- + +## Story Sizing Guidelines + +### Story Points Reference + +**1-2 Points (Few hours):** +- Simple UI change +- Copy update +- Minor configuration + +**3-5 Points (1-2 days):** +- New form with validation +- Simple API endpoint +- Basic feature toggle + +**8 Points (3-5 days):** +- Complex form with business logic +- Integration with third-party service +- New database schema with migration + +**13+ Points (1+ weeks):** +- Too large! Split the story +- Consider as an Epic + +--- + +## Templates for Common Scenarios + +### Registration/Sign-Up + +``` +As a new visitor, +I want to create an account with my email, +So that I can access personalized features. + +Acceptance Criteria: +- [ ] Email and password required (password: min 8 chars, 1 number, 1 special char) +- [ ] Email validation and duplicate check +- [ ] Confirmation email sent upon registration +- [ ] Automatically logged in after email confirmation +- [ ] Option to sign up with Google/Apple (social auth) +``` + +### Data Export + +``` +As a user, +I want to export my data as CSV, +So that I can analyze it in Excel. + +Acceptance Criteria: +- [ ] Export button in settings +- [ ] Includes all user data (specify fields) +- [ ] File downloads immediately (or email if > 10MB) +- [ ] Filename format: "export_[username]_[date].csv" +- [ ] Respects data privacy regulations (only user's own data) +``` + +### Error Handling + +``` +As a user, +I want to see helpful error messages, +So that I know how to fix issues. + +Acceptance Criteria: +- [ ] Error messages are specific (not generic "Error occurred") +- [ ] Suggest actionable next steps +- [ ] Display in user's language +- [ ] Don't expose technical details (stack traces) +- [ ] Log errors for debugging (backend) +``` + +--- + +## Best Practices Summary + +1. **Write from user perspective**, not system perspective +2. **Focus on value/benefit**, not just functionality +3. **Keep stories small** (completable in one sprint) +4. **Make acceptance criteria testable** +5. **Use consistent format** across your team +6. **Include edge cases** in acceptance criteria +7. **Collaborate** with engineers and designers when writing +8. **Refine regularly** based on new learnings +9. **Link to mockups/designs** when relevant +10. **Prioritize ruthlessly** (must/should/nice-to-have) + +--- + +## Additional Resources + +### User Story Template + +``` +Title: [Concise feature name] + +As a [specific user type], +I want to [action/capability], +So that [benefit/value]. + +Acceptance Criteria: +- [ ] [Testable criterion 1] +- [ ] [Testable criterion 2] +- [ ] [Edge case handling] + +Priority: [Must Have / Should Have / Nice to Have] +Story Points: [1/2/3/5/8/13] +Dependencies: [List if any] +Design: [Link to mockups] +Notes: [Additional context] +``` + +### Epic vs Story vs Task + +**Epic:** Large body of work (multiple sprints) +- Example: "User Authentication System" + +**Story:** Deliverable value (one sprint) +- Example: "As a user, I want to reset my password..." + +**Task:** Implementation step (hours/days) +- Example: "Create password reset API endpoint" + +--- + +## Conclusion + +Effective user stories: +- Start with the user's perspective +- Clearly articulate value +- Include testable acceptance criteria +- Are sized appropriately +- Enable team collaboration + +Use these examples as templates, but adapt them to your product and users' specific needs! diff --git a/skills/prd-generator/scripts/generate_prd.sh b/skills/prd-generator/scripts/generate_prd.sh new file mode 100755 index 0000000..d868236 --- /dev/null +++ b/skills/prd-generator/scripts/generate_prd.sh @@ -0,0 +1,395 @@ +#!/bin/bash + +# PRD Generator Script +# Interactive workflow for generating Product Requirements Documents + +set -e + +# Colors for output +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +echo -e "${BLUE}╔════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ PRD Generator - Interactive Mode ║${NC}" +echo -e "${BLUE}╔════════════════════════════════════════╗${NC}" +echo "" + +# Get script directory +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SKILL_DIR="$(dirname "$SCRIPT_DIR")" + +# Check if template exists +TEMPLATE_FILE="$SKILL_DIR/references/prd_template.md" +if [ ! -f "$TEMPLATE_FILE" ]; then + echo -e "${RED}✗ Error: PRD template not found at $TEMPLATE_FILE${NC}" + exit 1 +fi + +# Function to prompt for input +prompt_input() { + local prompt="$1" + local var_name="$2" + local required="$3" + + while true; do + echo -e "${YELLOW}${prompt}${NC}" + read -r input + + if [ -n "$input" ]; then + eval "$var_name='$input'" + break + elif [ "$required" != "true" ]; then + eval "$var_name=''" + break + else + echo -e "${RED}This field is required. Please provide a value.${NC}" + fi + done +} + +# Gather basic information +echo -e "${GREEN}Step 1: Basic Information${NC}" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" + +prompt_input "Feature/Product Name:" PRODUCT_NAME true +prompt_input "One-line Description:" DESCRIPTION true +prompt_input "Output Filename (default: ${PRODUCT_NAME// /_}_prd.md):" OUTPUT_FILE false + +# Set default output file if not provided +if [ -z "$OUTPUT_FILE" ]; then + OUTPUT_FILE="${PRODUCT_NAME// /_}_prd.md" + OUTPUT_FILE=$(echo "$OUTPUT_FILE" | tr '[:upper:]' '[:lower:]') +fi + +echo "" +echo -e "${GREEN}Step 2: Problem & Context${NC}" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" + +prompt_input "What problem are you solving?" PROBLEM true +prompt_input "Who are the primary users?" PRIMARY_USERS true +prompt_input "What are the key business goals?" BUSINESS_GOALS true + +echo "" +echo -e "${GREEN}Step 3: Success & Scope${NC}" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" + +prompt_input "How will you measure success?" SUCCESS_METRICS true +prompt_input "Target launch date (or 'TBD'):" TIMELINE false +prompt_input "What's explicitly OUT of scope?" OUT_OF_SCOPE false + +echo "" +echo -e "${GREEN}Step 4: PRD Type${NC}" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" +echo "Select PRD type:" +echo " 1) Standard (comprehensive)" +echo " 2) Lean (streamlined)" +echo " 3) One-Pager (executive summary)" +echo "" + +while true; do + read -p "Enter choice (1-3): " prd_type + case $prd_type in + 1) PRD_TYPE="standard"; break;; + 2) PRD_TYPE="lean"; break;; + 3) PRD_TYPE="one-pager"; break;; + *) echo -e "${RED}Invalid choice. Please enter 1, 2, or 3.${NC}";; + esac +done + +# Generate PRD +echo "" +echo -e "${BLUE}Generating PRD...${NC}" +echo "" + +# Create PRD from template +cat > "$OUTPUT_FILE" << EOF +# Product Requirements Document: $PRODUCT_NAME + +**Status:** Draft +**Author:** $(whoami) +**Date:** $(date +%Y-%m-%d) +**Last Updated:** $(date +%Y-%m-%d) + +--- + +## Executive Summary + +$DESCRIPTION + +This PRD outlines the requirements for $PRODUCT_NAME, addressing the need to $PROBLEM for $PRIMARY_USERS. + +--- + +## Problem Statement + +### The Problem + +$PROBLEM + +### Impact + +Without this feature/product, users experience [describe pain points]. + +### Why Now? + +$BUSINESS_GOALS + +--- + +## Goals & Objectives + +### Business Goals + +$BUSINESS_GOALS + +### User Goals + +- [User goal 1] +- [User goal 2] +- [User goal 3] + +### Success Criteria + +$SUCCESS_METRICS + +--- + +## User Personas + +### Primary User: $PRIMARY_USERS + +**Demographics:** +- [Add demographic info] + +**Behaviors:** +- [Add behavioral patterns] + +**Needs:** +- [Add key needs] + +**Pain Points:** +- [Add pain points] + +--- + +## User Stories & Requirements + +### Core User Stories + +#### Story 1: [Feature Name] + +**User Story:** +\`\`\` +As a [$PRIMARY_USERS], +I want to [action], +So that [benefit]. +\`\`\` + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] [Criterion 3] + +**Priority:** Must Have + +--- + +#### Story 2: [Feature Name] + +**User Story:** +\`\`\` +As a [user type], +I want to [action], +So that [benefit]. +\`\`\` + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] [Criterion 3] + +**Priority:** Should Have + +--- + +## Success Metrics + +### Key Performance Indicators (KPIs) + +$SUCCESS_METRICS + +### Measurement Plan + +| Metric | Baseline | Target | Measurement Method | +|--------|----------|--------|-------------------| +| [Metric 1] | [Current value] | [Target value] | [How to measure] | +| [Metric 2] | [Current value] | [Target value] | [How to measure] | + +--- + +## Scope + +### In Scope + +- [Feature/capability 1] +- [Feature/capability 2] +- [Feature/capability 3] + +### Out of Scope + +$OUT_OF_SCOPE + +- [Explicitly excluded item 1] +- [Explicitly excluded item 2] + +### Future Considerations + +- [Potential future enhancement 1] +- [Potential future enhancement 2] + +--- + +## Technical Considerations + +### Architecture + +[High-level technical approach] + +### Dependencies + +- **External APIs:** [List APIs] +- **Services:** [List services] +- **Libraries:** [List libraries] + +### Security Requirements + +- [Security requirement 1] +- [Security requirement 2] + +### Performance Requirements + +- [Performance requirement 1] +- [Performance requirement 2] + +### Data Considerations + +- [Data storage needs] +- [Data migration needs] +- [Privacy considerations] + +--- + +## Design & UX Requirements + +### User Experience + +[Describe key UX principles and patterns] + +### Visual Design + +[Reference design system, mockups, or wireframes] + +### Accessibility + +- WCAG 2.1 Level AA compliance required +- Keyboard navigation support +- Screen reader compatibility + +### Responsive Design + +- Mobile support: [Yes/No/Details] +- Tablet support: [Yes/No/Details] +- Desktop support: [Yes/No/Details] + +--- + +## Timeline & Milestones + +**Target Launch:** $TIMELINE + +### Phases + +| Phase | Deliverables | Target Date | +|-------|-------------|-------------| +| Discovery | Requirements finalized, designs approved | [Date] | +| Development | Core functionality complete | [Date] | +| Testing | QA complete, bugs resolved | [Date] | +| Launch | Feature live in production | $TIMELINE | + +--- + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation Strategy | +|------|--------|------------|-------------------| +| [Risk 1] | High/Med/Low | High/Med/Low | [How to mitigate] | +| [Risk 2] | High/Med/Low | High/Med/Low | [How to mitigate] | + +--- + +## Dependencies & Assumptions + +### Dependencies + +- [Dependency 1] +- [Dependency 2] + +### Assumptions + +- [Assumption 1] +- [Assumption 2] + +--- + +## Open Questions + +- [ ] [Question 1] +- [ ] [Question 2] +- [ ] [Question 3] + +--- + +## Stakeholder Sign-Off + +| Stakeholder | Role | Status | Date | +|------------|------|--------|------| +| [Name] | Product Lead | Pending | - | +| [Name] | Engineering Lead | Pending | - | +| [Name] | Design Lead | Pending | - | + +--- + +## Appendix + +### References + +- [Reference 1] +- [Reference 2] + +### Change Log + +| Date | Author | Changes | +|------|--------|---------| +| $(date +%Y-%m-%d) | $(whoami) | Initial draft | + +EOF + +echo -e "${GREEN}✓ PRD generated successfully!${NC}" +echo "" +echo -e "Output file: ${BLUE}$OUTPUT_FILE${NC}" +echo "" +echo -e "${YELLOW}Next steps:${NC}" +echo " 1. Review and fill in the placeholder sections" +echo " 2. Add specific user stories and acceptance criteria" +echo " 3. Attach mockups/wireframes if available" +echo " 4. Share with stakeholders for review" +echo " 5. Run validation: scripts/validate_prd.sh $OUTPUT_FILE" +echo "" +echo -e "${GREEN}✓ Done!${NC}" diff --git a/skills/prd-generator/scripts/validate_prd.sh b/skills/prd-generator/scripts/validate_prd.sh new file mode 100755 index 0000000..9625169 --- /dev/null +++ b/skills/prd-generator/scripts/validate_prd.sh @@ -0,0 +1,298 @@ +#!/bin/bash + +# PRD Validation Script +# Checks PRD completeness and quality + +set -e + +# Colors for output +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +# Default values +VERBOSE=false +SECTIONS="all" + +# Usage function +usage() { + echo "Usage: $0 [options]" + echo "" + echo "Options:" + echo " --verbose Show detailed suggestions" + echo " --sections Check specific sections only (comma-separated)" + echo " e.g., --sections user-stories,metrics" + echo "" + echo "Example:" + echo " $0 my_prd.md" + echo " $0 my_prd.md --verbose" + echo " $0 my_prd.md --sections user-stories,metrics" + exit 1 +} + +# Parse arguments +if [ $# -lt 1 ]; then + usage +fi + +PRD_FILE="$1" +shift + +while [[ $# -gt 0 ]]; do + case $1 in + --verbose) + VERBOSE=true + shift + ;; + --sections) + SECTIONS="$2" + shift 2 + ;; + *) + echo -e "${RED}Unknown option: $1${NC}" + usage + ;; + esac +done + +# Check if file exists +if [ ! -f "$PRD_FILE" ]; then + echo -e "${RED}✗ Error: File not found: $PRD_FILE${NC}" + exit 1 +fi + +echo -e "${BLUE}╔════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ PRD Validation Report ║${NC}" +echo -e "${BLUE}╚════════════════════════════════════════╝${NC}" +echo "" +echo -e "File: ${BLUE}$PRD_FILE${NC}" +echo "" + +# Counters +ISSUES_FOUND=0 +WARNINGS=0 +CHECKS_PASSED=0 + +# Function to check section exists +check_section() { + local section_name="$1" + local section_pattern="$2" + local required="$3" + + if grep -q "$section_pattern" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} $section_name section found" + ((CHECKS_PASSED++)) + return 0 + else + if [ "$required" = "true" ]; then + echo -e "${RED}✗${NC} $section_name section missing (REQUIRED)" + ((ISSUES_FOUND++)) + else + echo -e "${YELLOW}⚠${NC} $section_name section missing (recommended)" + ((WARNINGS++)) + fi + return 1 + fi +} + +# Function to check content quality +check_content() { + local check_name="$1" + local pattern="$2" + local error_msg="$3" + + if grep -q "$pattern" "$PRD_FILE"; then + echo -e "${YELLOW}⚠${NC} $check_name: $error_msg" + ((WARNINGS++)) + return 1 + else + echo -e "${GREEN}✓${NC} $check_name passed" + ((CHECKS_PASSED++)) + return 0 + fi +} + +echo -e "${BLUE}━━━ Section Completeness ━━━${NC}" +echo "" + +# Required sections +check_section "Problem Statement" "##.*Problem Statement" true +check_section "Goals & Objectives" "##.*Goals.*Objectives" true +check_section "User Stories" "##.*User Stories" true +check_section "Success Metrics" "##.*Success Metrics" true +check_section "Scope" "##.*Scope" true + +echo "" +echo -e "${BLUE}━━━ Recommended Sections ━━━${NC}" +echo "" + +# Recommended sections +check_section "Executive Summary" "##.*Executive Summary" false +check_section "User Personas" "##.*User Personas" false +check_section "Technical Considerations" "##.*Technical Considerations" false +check_section "Design & UX Requirements" "##.*Design.*UX" false +check_section "Timeline & Milestones" "##.*Timeline.*Milestones" false +check_section "Risks & Mitigation" "##.*Risks.*Mitigation" false + +echo "" +echo -e "${BLUE}━━━ Content Quality Checks ━━━${NC}" +echo "" + +# Check for placeholder text +check_content "Placeholder text" "\[.*\]" "Contains placeholder brackets - fill in all placeholders" + +# Check for TBD/TODO +check_content "TBD markers" "TBD\|TODO" "Contains TBD/TODO markers - resolve all open items" + +# Check for empty sections +if grep -q "^##.*\n\n##" "$PRD_FILE"; then + echo -e "${YELLOW}⚠${NC} Empty sections detected" + ((WARNINGS++)) +else + echo -e "${GREEN}✓${NC} No empty sections" + ((CHECKS_PASSED++)) +fi + +# Check for user story format +echo "" +echo -e "${BLUE}━━━ User Story Validation ━━━${NC}" +echo "" + +USER_STORY_COUNT=$(grep -c "As a.*I want.*So that" "$PRD_FILE" || true) +if [ "$USER_STORY_COUNT" -gt 0 ]; then + echo -e "${GREEN}✓${NC} Found $USER_STORY_COUNT properly formatted user stories" + ((CHECKS_PASSED++)) + + # Check for acceptance criteria + AC_COUNT=$(grep -c "Acceptance Criteria" "$PRD_FILE" || true) + if [ "$AC_COUNT" -ge "$USER_STORY_COUNT" ]; then + echo -e "${GREEN}✓${NC} All user stories have acceptance criteria" + ((CHECKS_PASSED++)) + else + echo -e "${YELLOW}⚠${NC} Some user stories may be missing acceptance criteria" + ((WARNINGS++)) + fi +else + echo -e "${RED}✗${NC} No properly formatted user stories found" + echo -e " Expected format: 'As a [user], I want [action], So that [benefit]'" + ((ISSUES_FOUND++)) +fi + +# Check for success metrics +echo "" +echo -e "${BLUE}━━━ Metrics Validation ━━━${NC}" +echo "" + +if grep -q "KPI\|metric\|measure" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} Success metrics mentioned" + ((CHECKS_PASSED++)) + + # Check for quantifiable metrics + if grep -q "[0-9]\+%" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} Contains quantifiable metrics (percentages found)" + ((CHECKS_PASSED++)) + else + echo -e "${YELLOW}⚠${NC} Consider adding quantifiable targets (%, numbers, etc.)" + ((WARNINGS++)) + fi +else + echo -e "${RED}✗${NC} Success metrics not clearly defined" + ((ISSUES_FOUND++)) +fi + +# Check for scope definition +echo "" +echo -e "${BLUE}━━━ Scope Validation ━━━${NC}" +echo "" + +IN_SCOPE=false +OUT_SCOPE=false + +if grep -qi "in scope\|in-scope" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} In-scope section defined" + IN_SCOPE=true + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} In-scope section not clearly defined" + ((WARNINGS++)) +fi + +if grep -qi "out of scope\|out-of-scope" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} Out-of-scope section defined" + OUT_SCOPE=true + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Out-of-scope section not defined (prevents scope creep)" + ((WARNINGS++)) +fi + +# Document quality checks +echo "" +echo -e "${BLUE}━━━ Document Quality ━━━${NC}" +echo "" + +# Check word count +WORD_COUNT=$(wc -w < "$PRD_FILE") +echo -e "Word count: $WORD_COUNT" + +if [ "$WORD_COUNT" -lt 500 ]; then + echo -e "${YELLOW}⚠${NC} Document seems short for a PRD (< 500 words)" + ((WARNINGS++)) +elif [ "$WORD_COUNT" -gt 5000 ]; then + echo -e "${YELLOW}⚠${NC} Document is very long (> 5000 words) - consider splitting" + ((WARNINGS++)) +else + echo -e "${GREEN}✓${NC} Document length appropriate" + ((CHECKS_PASSED++)) +fi + +# Check for headers hierarchy +if grep -q "^#\s" "$PRD_FILE"; then + echo -e "${GREEN}✓${NC} Proper heading structure" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Check heading hierarchy (should start with # not ##)" + ((WARNINGS++)) +fi + +# Final Summary +echo "" +echo -e "${BLUE}╔════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ Validation Summary ║${NC}" +echo -e "${BLUE}╚════════════════════════════════════════╝${NC}" +echo "" +echo -e "Checks passed: ${GREEN}$CHECKS_PASSED${NC}" +echo -e "Warnings: ${YELLOW}$WARNINGS${NC}" +echo -e "Issues found: ${RED}$ISSUES_FOUND${NC}" +echo "" + +# Recommendations +if [ "$VERBOSE" = true ]; then + echo -e "${BLUE}━━━ Recommendations ━━━${NC}" + echo "" + echo "1. Ensure all required sections are present" + echo "2. Fill in all placeholder text marked with [brackets]" + echo "3. Use the user story format: 'As a [user], I want [action], So that [benefit]'" + echo "4. Include specific, measurable success metrics" + echo "5. Clearly define what's in and out of scope" + echo "6. Add acceptance criteria for all user stories" + echo "7. Review with stakeholders before finalizing" + echo "" +fi + +# Exit code +if [ "$ISSUES_FOUND" -gt 0 ]; then + echo -e "${RED}❌ PRD validation failed${NC}" + echo -e " Address $ISSUES_FOUND critical issue(s) before proceeding" + exit 1 +elif [ "$WARNINGS" -gt 0 ]; then + echo -e "${YELLOW}⚠ PRD validation passed with warnings${NC}" + echo -e " Consider addressing $WARNINGS warning(s) to improve quality" + exit 0 +else + echo -e "${GREEN}✅ PRD validation passed!${NC}" + echo -e " Document looks ready for stakeholder review" + exit 0 +fi