Prd

Format Questions Like This:

1. What is the primary goal of this feature?
   A. Improve user onboarding experience
   B. Increase user retention
   C. Reduce support burden
   D. Other: [please specify]

2. Who is the target user?
   A. New users only
   B. Existing users only
   C. All users
   D. Admin users only

3. What is the scope?
   A. Minimal viable version
   B. Full-featured implementation
   C. Just the backend/API
   D. Just the UI

This lets users respond with "1A, 2C, 3B" for quick iteration.

Step 2: Story Sizing (THE NUMBER ONE RULE)

Each story must be completable in ONE context window (~10 min of AI work).

Ralph spawns a fresh instance per iteration with no memory of previous work. If a story is too big, the AI runs out of context before finishing and produces broken code.

Right-sized stories:

• Add a database column and migration
• Add a single UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (MUST split):

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.

Step 3: Story Ordering (Dependencies First)

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 that aggregate data

Wrong order:

US-001: UI component (depends on schema that doesn't exist yet!)
US-002: Schema change

Step 4: Acceptance Criteria (Must Be Verifiable)

Each criterion must be something Ralph can CHECK, not something vague.

Good criteria (verifiable):

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Clicking delete shows confirmation dialog"
• "Typecheck passes"
• "Tests pass"

Bad criteria (vague):

• "Works correctly"
• "User can do X easily"
• "Good UX"
• "Handles edge cases"

Always include as final criterion:

"Typecheck passes"

For stories that change UI, also include:

"Verify changes work in browser"

PRD Structure

Generate the PRD with these sections:

1. Introduction

Brief description of the feature and the problem it solves.

2. Goals

Specific, measurable objectives (bullet list).

3. User Stories

Each story needs:

• ID: Sequential (US-001, US-002, etc.)
• Title: Short descriptive name
• Description: "As a [user], I want [feature] so that [benefit]"
• Acceptance Criteria: Verifiable checklist

Format:

### US-001: [Title]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] Specific verifiable criterion
- [ ] Another criterion
- [ ] Typecheck passes
- [ ] [UI stories] Verify changes work in browser

4. Non-Goals

What this feature will NOT include. Critical for scope.

5. Technical Considerations (Optional)

• Known constraints
• Existing components to reuse

Example PRD

# PRD: Task Priority System

## Introduction

Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering.

## Goals

- Allow assigning priority (high/medium/low) to any task
- Provide clear visual differentiation between priority levels
- Enable filtering by priority
- Default new tasks to medium priority

## User Stories

### US-001: Add priority field to database
**Description:** As a developer, I need to store task priority so it persists across sessions.

**Acceptance Criteria:**
- [ ] Add priority column: 'high' | 'medium' | 'low' (default 'medium')
- [ ] Generate and run migration successfully
- [ ] Typecheck passes

### US-002: Display priority indicator on task cards
**Description:** As a user, I want to see task priority at a glance so I know what needs attention first.

**Acceptance Criteria:**
- [ ] Each task card shows colored priority badge (red=high, yellow=medium, gray=low)
- [ ] Priority visible without hovering or clicking
- [ ] Typecheck passes
- [ ] Verify changes work in browser

### US-003: Add priority selector to task edit
**Description:** As a user, I want to change a task's priority when editing it.

**Acceptance Criteria:**
- [ ] Priority dropdown in task edit modal
- [ ] Shows current priority as selected
- [ ] Saves immediately on selection change
- [ ] Typecheck passes
- [ ] Verify changes work in browser

### US-004: Filter tasks by priority
**Description:** As a user, I want to filter the task list to see only high-priority items when I'm focused.

**Acceptance Criteria:**
- [ ] Filter dropdown with options: All | High | Medium | Low
- [ ] Filter persists in URL params
- [ ] Empty state message when no tasks match filter
- [ ] Typecheck passes
- [ ] Verify changes work in browser

## Non-Goals

- No priority-based notifications or reminders
- No automatic priority assignment based on due date
- No priority inheritance for subtasks

## Technical Considerations

- Reuse existing badge component with color variants
- Filter state managed via URL search params

Output

Save to PRD.md in the current directory.

Also create progress.txt:

# Progress Log

## Learnings
(Patterns discovered during implementation)

---

Checklist Before Saving

• Asked clarifying questions with lettered options
• Incorporated user's answers
• User stories use US-001 format
• Each story completable in ONE iteration (small enough)
• Stories ordered by dependency (schema -> backend -> frontend)
• All criteria are verifiable (not vague)
• Every story has "Typecheck passes" as criterion
• UI stories have "Verify changes work in browser"
• Non-goals section defines clear boundaries
• Saved PRD.md and progress.txt

Running the Ralph Loop

After generating a PRD, you can use the bundled ralph.sh script to automatically implement all user stories.

Setup

Copy the ralph.sh script from the plugin to your project:

cp ~/.claude/plugins/ralph-prd/scripts/ralph.sh ./
chmod +x ralph.sh

Usage

# Run with default settings (max 10 iterations, 2 second pause between)
./ralph.sh

# Run with custom max iterations
./ralph.sh 20

# Run with custom iterations and pause time
./ralph.sh 20 5

The script will automatically:

1. Read PRD.md and find incomplete tasks
2. Implement one task per iteration
3. Mark completed tasks with [x]
4. Stop when all tasks are complete or max iterations reached