Ralph PRD Converter

Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution.

The Job

Take a PRD (markdown file or text) and convert it to

prd.json

in your ralph directory.

Output Format

json

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Story Size: The Number One Rule

Each story must be completable in ONE Ralph iteration (one context window).

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

Right-sized stories:

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 big (split these):

"Build the entire dashboard" - Split into: schema, queries, UI components, filters
"Add authentication" - Split into: schema, middleware, login UI, session handling
"Refactor the API" - Split into one story per endpoint or pattern

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

Story Ordering: Dependencies First

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

Correct order:

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Dashboard/summary views that aggregate data

Wrong order:

UI component (depends on schema that does not exist yet)
Schema change

Acceptance Criteria: MACHINE-VERIFIABLE Required

Every criterion must be MACHINE-VERIFIABLE. If Ralph cannot verify it with a command, file check, or automated test, it is not a valid criterion.

Verification Types

Each criterion should be checkable by one of these methods:

Type	How to Verify	Example Criterion
Command exit code	Run command, check exit 0	"Typecheck passes" → `npm run build`
File check	Check file exists or has content	"File `docs/API.md` exists" → `ls docs/API.md`
Grep/content match	Search file for pattern	"Contains 'export default'" → `grep -q 'export default' file.ts`
Database query	Query returns expected result	"User table has email column" → `\d users` shows column
Browser automation	Dev-browser skill verifies visually	"Button is visible" → navigate and screenshot

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"

FORBIDDEN Criteria

Never use these vague terms — they cannot be machine-verified:

Forbidden Term	Why It Fails
"Works correctly"	What does "correctly" mean? No verification command.
"Good UX"	Subjective. Cannot be automated.
"Handles edge cases"	Which edge cases? Unspecified = unverifiable.
"Is performant"	What threshold? No measurable target.
"User-friendly"	Subjective opinion, not a testable state.
"Clean code"	Style preference, not machine-checkable.
"Properly implemented"	Circular definition, no verification method.

Vague to Specific Conversion

When you encounter vague requirements, convert them:

Vague (FORBIDDEN)	Specific (VERIFIABLE)
"Works correctly"	"Returns 200 status code for valid input"
"Good UX"	"Form shows inline validation errors within 100ms"
"Handles edge cases"	"Returns 400 error when email is empty"
"Is performant"	"Query completes in under 100ms for 1000 rows"
"User-friendly error messages"	"Error div contains text 'Invalid email format'"
"Secure authentication"	"Password is hashed with bcrypt before storage"
"Responsive design"	"Component renders at 320px, 768px, and 1024px widths"

Always include as final criterion:

"Typecheck passes"

For stories with testable logic, also include:

"Tests pass"

For stories that change UI, also include:

"Verify in browser using dev-browser skill"

Frontend stories are NOT complete until visually verified. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

Conversion Rules

Each user story becomes one JSON entry
IDs: Sequential (US-001, US-002, etc.)
Priority: Based on dependency order, then document order
All stories:
```
passes: false
```
and empty
```
notes
```
branchName: Derive from feature name, kebab-case, prefixed with
```
ralph/
```
Always add: "Typecheck passes" to every story's acceptance criteria

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add user notification system"

Split into:

US-001: Add notifications table to database
US-002: Create notification service for sending notifications
US-003: Add notification bell icon to header
US-004: Create notification dropdown panel
US-005: Add mark-as-read functionality
US-006: Add notification preferences page

Each is one focused change that can be completed and verified independently.

Example

Input PRD:

markdown

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

Output prd.json: