afrexai-prd-engine

name	afrexai-prd-engine
description	PRD Engine

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

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

# 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]


 Page load: <[X]ms
 API response: <[X]ms
 Concurrent users: [X]


 [Data handling requirements]
 [Auth/permissions needed]
 [PII considerations]




 [ ] Feature flag: [flag name]
 [ ] Beta group: [who]
 [ ] % rollout: [10% → 50% → 100%]
 [ ] Rollback plan: [how]


 [ ] QA sign-off
 [ ] Analytics events implemented
 [ ] Monitoring/alerts configured
 [ ] Documentation updated
 [ ] Support team briefed
 [ ] Stakeholders notified



| Metric | Current | Target | Timeframe |
|--------|---------|--------|-----------|
| [Primary metric] | [X] | [Y] | [Z weeks] |
| [Secondary metric] | [X] | [Y] | [Z weeks] |


  [What to look at]
  [What to measure]
  [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

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

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:

# 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:

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

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