Prd

# PRD Skill

Create and manage Product Requirements Documents (PRDs) for feature planning.

## What is a PRD?

A **PRD (Product Requirements Document)** is a structured specification that:

1. Breaks a feature into **small, independent user stories** 2. Defines **verifiable acceptance criteria** for each story 3. Orders tasks by **dependency** (schema → backend → UI)

## Quick Start

1. Create/edit `agents/prd.json` in the project 2. Define user stories with acceptance criteria 3. Track progress by updating `passes: false` → `true`

## prd.json Format

```json { "project": "MyApp", "branchName": "ralph/feature-name", "description": "Short description of the feature", "userStories": [ { "id": "US-001", "title": "Add priority field to database", "description": "As a developer, I need to store task priority.", "acceptanceCriteria": [ "Add priority column: 'high' | 'medium' | 'low'", "Generate and run migration", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" } ] } ```

### Field Descriptions

| Field | Description | |-------|-------------| | `project` | Project name for context | | `branchName` | Git branch for this feature (prefix with `ralph/`) | | `description` | One-line feature summary | | `userStories` | List of stories to complete | | `userStories[].id` | Unique identifier (US-001, US-002) | | `userStories[].title` | Short descriptive title | | `userStories[].description` | "As a [user], I want [feature] so that [benefit]" | | `userStories[].acceptanceCriteria` | Verifiable checklist items | | `userStories[].priority` | Execution order (1 = first) | | `userStories[].passes` | Completion status (`false` → `true` when done) | | `userStories[].notes` | Runtime notes added by agent |

## Story Sizing

**Each story should be completable in one context window.**

### ✅ Right-sized: - Add a database column and migration - Add a UI component to an existing page - Update a server action with new logic - Add a filter dropdown to a list

### ❌ Too large (split these): - "Build the entire dashboard" → Split into: schema, queries, UI, filters - "Add authentication" → Split into: schema, middleware, login UI, session

## Story Ordering

Stories execute in priority order. Earlier stories must NOT depend on later ones.

**Correct order:** 1. Schema/database changes (migrations) 2. Server actions / backend logic 3. UI components that use the backend 4. Dashboard/summary views

## Acceptance Criteria

Must be verifiable, not vague.

### ✅ Good: - "Add `status` column to tasks table with default 'pending'" - "Filter dropdown has options: All, Active, Completed" - "Typecheck passes"

### ❌ Bad: - "Works correctly" - "User can do X easily"

**Always include:** `"Typecheck passes"`

## Progress Tracking

Update `passes: true` when a story is complete. Use `notes` field for runtime observations:

```json "notes": "Used IF NOT EXISTS for migrations" ```

## Quick Reference

| Action | Command | |--------|---------| | Create PRD | Save to `agents/prd.json` | | Check status | `cat prd.json | jq '.userStories[] | {id, passes}'` | | View incomplete | `jq '.userStories[] | select(.passes == false)' prd.json` |

## Resources

See `references/` for detailed documentation: - `agent-usage.md` - How AI agents execute PRDs (Claude Code, OpenCode, etc.) - `workflows.md` - Sequential workflow patterns - `output-patterns.md` - Templates and examples