ralph

Ralph JSON Converter

Turn an existing PRD into the prd.json document Ralph uses to drive autonomous execution.

---

Goal

Take a PRD in Markdown or plain text and produce prd.json inside the Ralph workspace.

---

Required Output Shape

Use this structure:

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

---

Most Important Rule: Keep Stories Small

Every story must fit within a single Ralph iteration.

Ralph starts each iteration with a fresh Amp session. If a story spans too much code or too many concerns, the model is likely to lose context and leave the work incomplete.

Good story sizes

• Add one database field plus its migration
• Add one focused backend behavior
• Add one UI element to an existing screen
• Add one filter or control to an existing list

Stories that are too large

Break down items like these:

• "Build the whole dashboard"
• "Add authentication"
• "Refactor the API"

Instead, split them into smaller steps such as schema work, backend logic, UI pieces, and follow-up interactions.

Practical rule: if the change cannot be explained clearly in 2-3 sentences, split it further.

---

Order Stories by Dependency

Ralph executes stories according to priority. Earlier work must unlock later work, not depend on it.

Preferred order

1. Database or schema changes
2. Backend or server-side behavior
3. UI work that depends on the backend
4. Summary, reporting, or aggregation views

Avoid this pattern

1. UI story that assumes missing backend or schema support
2. Supporting backend/schema story that should have come first