ralph-convert-prd

<quick_start>

1. Read the user’s PRD or feature requirements
2. Read SPEC.md if available (for verification environment info)
3. Break down into atomic user stories (one context window each)
4. Classify each story with storyType
5. Generate verificationCommands with real runtime checks
6. Set blockedBy dependencies
7. Order stories by dependency (schema → backend → UI → dashboard)
8. Output valid tasks/prd.json </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

1. Schema/database changes
2. Server actions and backend logic
3. UI components
4. Dashboard/summary views

Never reference something that doesn’t exist yet.

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”

UI-focused stories MUST also include: "Verify in browser using Playwright e2e test"

By storyType:

Static checks (typecheck) are always included as baseline. Runtime validation is additionally required. </essential_principles>

<output_format>

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description]",
  "testCommands": {
    "unit": "npm test",
    "integration": "npm run test:integration",
    "e2e": "npx playwright test",
    "typecheck": "npm run typecheck"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "storyType": "database",
      "acceptanceCriteria": [
        "Specific criterion 1",
        "Specific criterion 2",
        "Typecheck passes"
      ],
      "verificationCommands": [
        { "command": "npm run typecheck", "expect": "exit_code:0" },
        { "command": "curl -s http://localhost:3000/api/tasks | jq length", "expect": "not_empty" }
      ],
      "status": "pending",
      "priority": 1,
      "attempts": 0,
      "maxAttempts": 3,
      "notes": "",
      "blockedBy": [],
      "docsToUpdate": ["README.md"],
      "completedAt": null,
      "lastAttemptLog": ""
    }
  ]
}

Field requirements:

• id: Sequential US-001, US-002, etc.
• title: Short, descriptive action
• description: User story format (As a… I want… so that…)
• storyType: One of "backend" | "frontend" | "database" | "api" | "infra" | "test"
• acceptanceCriteria: Array of specific, verifiable criteria
• verificationCommands: Array of {command, expect} with real runtime checks
• status: Always "pending" initially
• priority: Execution order (1 = first)
• attempts: Always 0 initially
• maxAttempts: Default 3 (increase for complex stories)
• notes: Empty string initially
• blockedBy: Array of story IDs that must be "done" first
• docsToUpdate: Array of file paths to documentation that must be updated when story is done (e.g., "README.md", "docs/api.md", "CHANGELOG.md")
• completedAt: Always null initially
• lastAttemptLog: Empty string initially

Expect matchers for verificationCommands:

• exit_code:0 — command exits with code 0
• exit_code:N — command exits with specific code N
• contains:STRING — stdout contains STRING
• not_empty — stdout is non-empty
• matches:REGEX — stdout matches regex pattern </output_format>

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

• Previous runs archived (if applicable)
• Each story completable in one iteration
• Each story has a storyType assigned
• Stories ordered by dependency (no forward references)
• blockedBy dependencies are set correctly
• All stories include “Typecheck passes” in acceptanceCriteria
• UI stories include Playwright verification
• Every story has verificationCommands with at least one runtime check
• Acceptance criteria are verifiable, not vague
• No story depends on later stories
• docsToUpdate lists relevant docs for each story
• status is "pending", attempts is 0, maxAttempts is set </pre_save_checklist>

<success_criteria> Conversion is complete when:

• All features from PRD are captured as user stories
• Each story is atomic (one context window)
• Each story has a storyType assigned
• Stories are properly ordered by dependency with blockedBy set
• All acceptance criteria are specific and verifiable
• Mandatory criteria (“Typecheck passes”) present on all stories
• Every story has verificationCommands with real runtime checks
• UI stories include Playwright verification
• Valid JSON structure with all required fields
• Pre-save checklist passes </success_criteria>