ralph-convert-prd

Transform existing Product Requirements Documents into the structured `prd.json` format used by the Ralph autonomous agent system. Each story must be completable in one LLM context window to prevent broken code from context overflow.

<quick_start>

Read the user's PRD or feature requirements
Break down into atomic user stories (one context window each)
Order stories by dependency (schema → backend → UI → dashboard)
Output valid prd.json with verifiable acceptance criteria </quick_start>

<essential_principles> Critical Rule: Each story must be completable in ONE Ralph iteration (one context window).

Stories that are too large cause the LLM to run out of context before completion, resulting in broken code.

Right-sized stories:

Add a database column
Create a UI component
Update server actions
Implement a filter

Too large (split these):

Build entire dashboards
Add authentication systems
Refactor entire APIs

Stories must execute sequentially without forward dependencies:

Schema/database changes
Server actions and backend logic
UI components
Dashboard/summary views

Never reference something that doesn't exist yet.

Each criterion must be verifiable and specific. Avoid vague language.

Good criteria:

"Add status column with values: 'pending' | 'in_progress' | 'done'"
"Filter dropdown includes: All, Active, Completed"
"Clicking delete shows confirmation dialog"

Bad criteria (too vague):

"Works correctly"
"Good UX"
"Handles edge cases"

Every story MUST include: `"Typecheck passes"`

UI-focused stories MUST also include: "Verify in browser using dev-browser skill" </essential_principles>

<output_format>

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

Field requirements:

id: Sequential US-001, US-002, etc.
title: Short, descriptive action
description: User story format (As a... I want... so that...)
acceptanceCriteria: Array of specific, verifiable criteria
priority: Execution order (1 = first)
passes: Always false initially
notes: Empty string initially </output_format>

1. **Understand the PRD**: Read the full requirements document or feature request 2. **Identify components**: List all database changes, backend logic, UI elements 3. **Decompose into stories**: Break each component into atomic, one-iteration tasks 4. **Order by dependency**: Schema first, then backend, then UI, then dashboards 5. **Write acceptance criteria**: Make each criterion specific and verifiable 6. **Add mandatory criteria**: Ensure every story has "Typecheck passes" 7. **Generate prd.json**: Output the complete JSON structure 8. **Run pre-save checklist**: Verify all requirements before finalizing

<pre_save_checklist> Before outputting the final prd.json, verify:

Previous runs archived (if applicable)
Each story completable in one iteration
Stories ordered by dependency (no forward references)
All stories include "Typecheck passes"
UI stories include browser verification criterion
Acceptance criteria are verifiable, not vague
No story depends on later stories </pre_save_checklist>

```json { "id": "US-001", "title": "Add task status column to database", "description": "As a developer, I want a status column on tasks so that we can track task progress", "acceptanceCriteria": [ "Add status column to tasks table with type enum('pending', 'in_progress', 'done')", "Default value is 'pending'", "Migration runs without errors", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" } ``` ```json { "id": "US-003", "title": "Add status filter dropdown to task list", "description": "As a user, I want to filter tasks by status so that I can focus on relevant tasks", "acceptanceCriteria": [ "Filter dropdown appears above task list", "Options: All, Pending, In Progress, Done", "Selecting option filters displayed tasks", "Filter persists on page refresh", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 3, "passes": false, "notes": "" } ```

<success_criteria> Conversion is complete when:

All features

...

SKILL.md

Repository

Repository Stats