Skill: 1kalin/afrexai-prd-engine (version 1.0.0)

# PRD Engine — Product Requirements That Ship Complete product requirements methodology: from idea to spec to shipped feature. Not just a JSON template — a full system for writing PRDs that developers actually follow and stakeholders actually approve. ## When to Use This Skill - Turning a vague idea into a buildable specification - Writing PRDs for new features, products, or major refactors - Reviewing/improving existing PRDs before sprint planning - Breaking epics into right-sized user stories - Creating technical design documents alongside product specs - Preparing specs for AI coding agents (Claude Code, Cursor, Copilot) --- ## Phase 1: Discovery Brief Before writing a single requirement, answer these questions. Skip this and you'll rewrite the PRD 3 times. ### Problem Validation Checklist ```yaml discovery_brief: problem: statement: "" # One sentence. If you need two, you don't understand it yet. who_has_it: "" # Specific persona, not "users" frequency: "" # Daily? Weekly? Once? (daily problems > occasional ones) current_workaround: "" # What do they do today? (no workaround = maybe not a real problem) evidence: - type: "" # support_ticket | user_interview | analytics | churned_user | sales_objection detail: "" date: "" impact: users_affected: "" # Number or percentage revenue_impact: "" # $ at risk or $ opportunity strategic_alignment: "" # Which company goal does this serve? constraints: deadline: "" # Hard date or flexible? budget: "" # Engineering weeks available dependencies: "" # What must exist first? regulatory: "" # Any compliance requirements? success_metrics: primary: "" # ONE metric that defines success secondary: [] # 2-3 supporting metrics measurement_method: "" # How will you actually measure this? target: "" # Specific number, not "improve" timeframe: "" # When do you expect to see results? ``` ### Problem Statement Formula **[Persona] needs [capability] because [reason], but currently [blocker], which causes [measurable impact].** Examples: - ❌ "Users need better onboarding" (vague, unmeasurable) - ✅ "New free-trial users (500/month) need to reach their first 'aha moment' within 10 minutes because 73% who don't will churn within 48 hours, but currently the average time-to-value is 34 minutes due to a 12-step setup wizard, which costs us ~$18K/month in lost conversions." ### Kill Criteria Before proceeding, check these. If any are true, STOP and push back: | Signal | Action | |--------|--------| | No evidence of the problem (just someone's opinion) | Demand evidence. Opinions aren't requirements. | | Solution already decided ("just build X") | Rewind to the problem. Solutions without problems = features nobody uses. | | Success metric is unmeasurable | Define how you'll measure it or don't build it. | | Affects <1% of users with no revenue impact | Deprioritize. Small problems with small impact = small returns. | | Scope keeps expanding during discovery | Scope lock. If everything is in scope, nothing is. | --- ## Phase 2: PRD Document ### PRD Template ```markdown # PRD: [Feature Name] **Author:** [Name] **Status:** Draft | In Review | Approved | In Progress | Shipped **Created:** YYYY-MM-DD **Last Updated:** YYYY-MM-DD **Approvers:** [Names + roles] ## 1. Problem & Opportunity [Problem statement from discovery brief — one paragraph max] ### Evidence - [Evidence point 1 — with data] - [Evidence point 2 — with data] ### Impact - Users affected: [number] - Revenue impact: [$ amount or % change] - Strategic goal: [which one] ## 2. Solution Overview [2-3 paragraphs max. What are we building and why this approach?] ### What This Is - [Bullet list of what's in scope] ### What This Is NOT - [Explicit exclusions — this prevents scope creep] ### Key Decisions Made | Decision | Options Considered | Chosen | Rationale | |----------|-------------------|--------|-----------| | [Decision 1] | A, B, C | B | [Why] | ## 3. User Stories [See Phase 3 below for story writing methodology] ## 4. Design & UX ### User Flow 1. User [action] → 2. System [response] → 3. User sees [outcome] ### Wireframes/Mockups [Link to Figma/screenshots or describe key screens] ### Edge Cases | Scenario | Expected Behavior | |----------|------------------| | [Edge case 1] | [What happens] | | [Edge case 2] | [What happens] | | Empty state | [What user sees with no data] | | Error state | [What user sees on failure] | | Slow connection | [Loading behavior] | ## 5. Technical Considerations ### Architecture Notes - [Key technical decisions] - [New services/APIs needed] - [Database changes] ### Dependencies - [External service X] - [Team Y's API] - [Library Z] ### Performance Requirements - Page load: <[X]ms - API response: <[X]ms - Concurrent users: [X] ### Security & Privacy - [Data handling requirements] - [Auth/permissions needed] - [PII considerations] ## 6. Release Plan ### Rollout Strategy - [ ] Feature flag: [flag name] - [ ] Beta group: [who] - [ ] % rollout: [10% → 50% → 100%] - [ ] Rollback plan: [how] ### Launch Checklist - [ ] QA sign-off - [ ] Analytics events implemented - [ ] Monitoring/alerts configured - [ ] Documentation updated - [ ] Support team briefed - [ ] Stakeholders notified ## 7. Success Criteria | Metric | Current | Target | Timeframe | |--------|---------|--------|-----------| | [Primary metric] | [X] | [Y] | [Z weeks] | | [Secondary metric] | [X] | [Y] | [Z weeks] | ### Post-Launch Review - **1-week check:** [What to look at] - **1-month review:** [What to measure] - **Kill/iterate decision:** [Criteria for each] ``` ### PRD Quality Rubric (score before sharing) | Dimension | 0-2 (Weak) | 3-4 (Adequate) | 5 (Strong) | Weight | |-----------|-----------|----------------|------------|--------| | **Problem clarity** | Vague, no data | Clear but thin evidence | Sharp statement + multiple evidence points | x4 | | **Scope discipline** | Everything in scope | Some boundaries | Explicit in/out + "what this is NOT" | x3 | | **Story quality** | Vague tasks | Stories with some criteria | INVEST stories + verifiable acceptance criteria | x4 | | **Edge cases** | None listed | Happy path + 1-2 edges | Comprehensive: empty, error, slow, permissions, concurrent | x3 | | **Success metrics** | "Improve X" | Metric + target | Metric + baseline + target + timeframe + measurement method | x3 | | **Technical feasibility** | No tech section | Architecture notes | Dependencies, performance, security, migration plan | x2 | | **Release plan** | None | "Ship it" | Feature flag + rollout % + rollback + launch checklist | x1 | **Scoring:** Sum (score × weight). Max = 100. - **80-100:** Ship-ready. Get approvals. - **60-79:** Solid but missing pieces. Fill gaps before review. - **40-59:** Needs work. Major sections incomplete. - **<40:** Start over or go back to discovery. --- ## Phase 3: User Story Methodology ### Story Format ```yaml story: id: "US-001" title: "" # Action-oriented: "Add priority field to tasks table" persona: "" # Who benefits narrative: "As a [persona], I want [capability] so that [benefit]" acceptance_criteria: - criterion: "" # Verifiable statement type: "functional" # functional | performance | security | ux priority: 1 # Execution order (dependencies first) size: "" # XS | S | M | L | XL status: "todo" # todo | in_progress | review | done notes: "" # Runtime observations depends_on: [] # Story IDs this depends on blocked_by: [] # External blockers ``` ### INVEST Checklist (every story must pass) | Letter | Criterion | Test | |--------|-----------|------| | **I** — Independent | Can be built without other incomplete stories | No circular dependencies | | **N** — Negotiable | Details can flex (the "what" is fixed, the "how" is flexible) | Multiple implementation approaches exist | | **V** — Valuable | Delivers user or business value on its own | Would a user/stakeholder care if only this shipped? | | **E** — Estimable | Team can size it | No major unknowns (if unknowns exist, add a spike first) | | **S** — Small | Completable in one sprint (or one context window for AI agents) | 1-3 days of work max | | **T** — Testable | Has verifiable acceptance criteria | Can write a test for each criterion | ### Acceptance Criteria Rules **Good criteria are:** - Binary (pass/fail, not subjective) - Specific (numbers, not adjectives) - Independent (testable in isolation) | ❌ Bad | ✅ Good | |--------|---------| | "Works correctly" | "Returns 200 with JSON body containing `id`, `name`, `status` fields" | | "Fast enough" | "API responds in <200ms at p95 with 100 concurrent users" | | "User-friendly" | "Form shows inline validation errors within 100ms of field blur" | | "Secure" | "Endpoint returns 403 for users without `admin` role" | | "Handles errors" | "On network timeout, shows retry button + cached data if available" | **Always include these universal criteria:** - `Typecheck passes (tsc --noEmit --strict)` (for TypeScript projects) - `All existing tests still pass` - `New functionality has test coverage` ### Story Sizing Guide | Size | Scope | Time | Example | |------|-------|------|---------| | **XS** | Config change, copy update, env var | <2 hours | "Update error message text" | | **S** | Single component/function, no new deps | 2-4 hours | "Add date picker to form" | | **M** | Feature slice: DB + API + UI | 1-2 days | "Add task priority with filter" | | **L** | Multi-component feature, new patterns | 2-3 days | "Add real-time notifications" | | **XL** | **Too big. Split it.** | — | — | ### Story Ordering: The Dependency Pyramid Always order stories bottom-up: ``` Level 1: Schema & Data (migrations, models, seed data) ↑ Level 2: Backend Logic (services, APIs, business rules) ↑ Level 3: Integration (API routes, auth, middleware) ↑ Level 4: UI Components (forms, tables, modals) ↑ Level 5: UX Polish (animations, empty states, loading) ↑ Level 6: Analytics & Monitoring (events, dashboards) ``` Each level depends ONLY on levels below it. Never build UI before the API exists. ### Splitting Strategies When a story is too big, split using one of these patterns: | Strategy | When to Use | Example | |----------|------------|---------| | **By layer** | Full-stack feature | "Add schema" → "Add API" → "Add UI" | | **By operation** | CRUD feature | "Create task" → "Read/list tasks" → "Update task" → "Delete task" | | **By persona** | Multi-role feature | "Admin creates template" → "User fills template" → "Viewer sees results" | | **By happy/sad path** | Complex flows | "Successful payment" → "Payment declined" → "Payment timeout" | | **By platform** | Cross-platform | "iOS support" → "Android support" → "Web support" | | **Spike + implement** | High uncertainty | "Spike: evaluate auth libraries (2h)" → "Implement auth with chosen library" | --- ## Phase 4: PRD for AI Coding Agents When the PRD will be executed by AI agents (Claude Code, Cursor, Copilot Workspace, etc.), add these adaptations: ### Agent-Optimized Story Format ```yaml agent_story: id: "US-001" title: "Add priority field to tasks table" context: | The tasks table is in src/db/schema.ts using Drizzle ORM. Priority values should be: high, medium, low (default: medium). See existing fields for naming conventions. acceptance_criteria: - "Add `priority` column to `tasks` table in src/db/schema.ts" - "Type: enum('high', 'medium', 'low'), default 'medium', not null" - "Generate migration: `npx drizzle-kit generate`" - "Run migration: `npx drizzle-kit push`" - "Verify: `tsc --noEmit --strict` passes" - "Verify: existing tests pass (`npm test`)" files_to_touch: - src/db/schema.ts - drizzle/ (generated migration) commands_to_run: - "npx drizzle-kit generate" - "npx drizzle-kit push" - "tsc --noEmit --strict" - "npm test" done_when: "All verify commands pass with exit code 0" ``` ### Agent-Specific Rules 1. **Be explicit about file paths.** Agents can't guess your project structure. 2. **Include verification commands.** Agents need a "definition of done" they can check. 3. **One context window per story.** If a story needs the agent to remember more than ~50 files, it's too big. 4. **List files to touch.** Reduces agent exploration time and prevents hallucination. 5. **Order matters even more.** Agents execute sequentially — wrong order = compounding errors. 6. **Include the commands.** Don't say "run the migration" — say `npx drizzle-kit push`. ### Project Context File For AI agent execution, create a `PROJECT_CONTEXT.md` alongside the PRD: ```markdown # Project Context ## Stack - Framework: [Next.js 14 / Express / etc.] - Language: [TypeScript strict mode] - Database: [PostgreSQL via Drizzle ORM] - Testing: [Vitest + Testing Library] - Styling: [Tailwind CSS] ## Key Directories - src/db/ — Database schema and migrations - src/api/ — API routes - src/components/ — React components - src/lib/ — Shared utilities - tests/ — Test files (mirror src/ structure) ## Conventions - File naming: kebab-case - Component naming: PascalCase - Max file length: 300 lines - Max function length: 50 lines - All exports typed, no `any` ## Commands - `npm run dev` — Start dev server - `npm test` — Run tests - `npm run build` — Production build - `tsc --noEmit --strict` — Type check - `npx drizzle-kit generate` — Generate migration - `npx drizzle-kit push` — Apply migration ## Current State - [What exists today relevant to the PRD] - [Any tech debt or gotchas the agent should know] ``` --- ## Phase 5: Review & Approval ### Review Checklist (before sharing the PRD) **Completeness:** - [ ] Problem statement has evidence (not just opinion) - [ ] "What this is NOT" section exists and is specific - [ ] Every story has ≥3 acceptance criteria - [ ] Edge cases table covers: empty state, error state, permissions, concurrent access - [ ] Success metrics have baseline + target + timeframe - [ ] Technical section addresses: performance, security, dependencies **Quality:** - [ ] No story larger than "L" (split XL stories) - [ ] All acceptance criteria are binary (pass/fail) - [ ] No circular dependencies between stories - [ ] Dependency pyramid ordering is correct - [ ] Release plan includes rollback strategy **Readability:** - [ ] Executive summary is <3 sentences - [ ] Non-engineers can understand the problem section - [ ] Engineers can start building from the stories section alone - [ ] No jargon without definition ### Approval Flow ``` Author writes PRD ↓ Self-review (score with rubric — must be ≥60) ↓ Peer review (another PM or tech lead) ↓ Engineering review (feasibility + sizing) ↓ Stakeholder approval (PM lead or product director) ↓ Status → Approved ↓ Sprint planning (stories → backlog) ``` ### Common Review Feedback (and how to fix it) | Feedback | Fix | |----------|-----| | "What problem does this solve?" | Your problem statement is weak. Add evidence. | | "This is too big" | Split into phases. Ship the smallest valuable slice first (MVP). | | "How do we know it worked?" | Your success metrics are vague. Add numbers + timeframe. | | "What about [edge case]?" | Your edge case table is incomplete. Add it. | | "When does this ship?" | Add timeline with milestones, not just a deadline. | | "Who approved this?" | Add approvers field and get explicit sign-offs. | --- ## Phase 6: Tracking & Iteration ### PRD Status Lifecycle ``` Draft → In Review → Approved → In Progress → Shipped → Post-Launch Review ↓ ↓ Rejected Iterate / Kill ``` ### Progress Tracking Track story completion in the PRD itself or a linked tracker: ```yaml progress: total_stories: 12 done: 7 in_progress: 2 blocked: 1 todo: 2 completion: "58%" blocked_items: - story: "US-008" blocker: "Waiting for payments API access from finance team" since: "2025-01-15" escalation: "Pinged finance lead, follow up Friday" velocity: stories_per_week: 3.5 estimated_completion: "2025-02-01" ``` ### Post-Launch Review Template ```yaml post_launch: shipped_date: "" review_date: "" # 2-4 weeks after ship metrics: primary: metric: "" baseline: "" target: "" actual: "" verdict: "" # hit | miss | exceeded secondary: - metric: "" actual: "" verdict: "" qualitative: user_feedback: [] support_tickets: "" # count related to this feature unexpected_outcomes: [] process_retro: what_went_well: [] what_didnt: [] estimation_accuracy: "" # actual vs estimated effort scope_changes: "" # what changed after approval decision: "" # iterate | maintain | deprecate | expand next_actions: [] ``` --- ## Quick Commands | Command | What It Does | |---------|-------------| | "Write a PRD for [feature]" | Full PRD from discovery through stories | | "Break this into stories" | Takes a feature description → user stories | | "Review this PRD" | Scores against quality rubric + gives specific feedback | | "Make this agent-ready" | Converts PRD stories to agent-optimized format | | "What's missing from this PRD?" | Gap analysis against the template | | "Split this story" | Takes a large story → smaller INVEST-compliant stories | | "Score this PRD" | Quality rubric scoring with dimension breakdown | | "Create project context for [project]" | Generates PROJECT_CONTEXT.md for AI agent execution | | "Post-launch review for [feature]" | Generates review template with metrics | | "Track progress" | Updates completion stats from story statuses |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)