ralph

Take a PRD (markdown file or text) and convert it to prd.json in your ralph directory.

---

```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": ""

}

]

}

```

---

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

Ralph spawns a fresh Amp 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.

---

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:

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

---

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 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.

---

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

---

If a PRD has big features, split them:

Original:

> "Add user notification system"

Split into:

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

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

---

Input PRD:

```markdown

# Task Status Feature

Add ability to mark tasks with different statuses.

• 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:

```json

{

"project": "TaskApp",

"branchName": "ralph/task-status",

"description": "Task Status Feature - Track task progress with status indicators",

"userStories": [

{

"id": "US-001",

"title": "Add status field to tasks table",

"description": "As a developer, I need to store task status in the database.",

"acceptanceCriteria": [

"Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",

"Generate and run migration successfully",

"Typecheck passes"

],

"priority": 1,

"passes": false,

"notes": ""

},

{

"id": "US-002",

"title": "Display status badge on task cards",

"description": "As a user, I want to see task status at a glance.",

"acceptanceCriteria": [

"Each task card shows colored status badge",

"Badge colors: gray=pending, blue=in_progress, green=done",

"Typecheck passes",

"Verify in browser using dev-browser skill"

],

"priority": 2,

"passes": false,

"notes": ""

},

{

"id": "US-003",

"title": "Add status toggle to task list rows",

"description": "As a user, I want to change task status directly from the list.",

"acceptanceCriteria": [

"Each row has status dropdown or toggle",

"Changing status saves immediately",

"UI updates without page refresh",

"Typecheck passes",

"Verify in browser using dev-browser skill"

],

"priority": 3,

"passes": false,

"notes": ""

},

{

"id": "US-004",

"title": "Filter tasks by status",

"description": "As a user, I want to filter the list to see only certain statuses.",

"acceptanceCriteria": [

"Filter dropdown: All | Pending | In Progress | Done",

"Filter persists in URL params",

"Typecheck passes",

"Verify in browser using dev-browser skill"

],

"priority": 4,

"passes": false,

"notes": ""

}

]

}

```

---

Before writing a new prd.json, check if there is an existing one from a different feature:

1. Read the current prd.json if it exists
2. Check if branchName differs from the new feature's branch name
3. If different AND progress.txt has content beyond the header:

- Create archive folder: archive/YYYY-MM-DD-feature-name/

- Copy current prd.json and progress.txt to archive

- Reset progress.txt with fresh header

The ralph.sh script handles this automatically when you run it, but if you are manually updating prd.json between runs, archive first.

---

Before writing prd.json, verify:

• [ ] Previous run archived (if prd.json exists with different branchName, archive it first!)
• [ ] ALL stories have passes: false (CRITICAL - never copy old pass status!)
• [ ] Each story is completable in one iteration (small enough)
• [ ] Stories are ordered by dependency (schema to backend to UI)
• [ ] Every story has "Typecheck passes" as criterion
• [ ] UI stories have "Verify in browser" as criterion
• [ ] Acceptance criteria are verifiable (not vague)
• [ ] No story depends on a later story

When creating a new prd.json, ALWAYS set passes: false for every story. Never:

• Copy pass status from an old prd.json
• Leave stories marked as passes: true
• Assume previous work carries over

Each new prd.json is a fresh start. The Ralph loop will mark stories as passes: true only after successfully implementing them.