Ralph PRD Converter
Converts existing PRDs to
for Ralph's autonomous execution loop.
The Job
Run Pre-flight Setup, then convert a PRD (markdown or text) into
.
Pre-flight Setup
- Project name — read field; fall back to directory basename.
- Copy runtime files — if missing in target project, copy from this skill's subdirectory to :
- Set NTFY_TOPIC — in , replace placeholder with actual project name. Skip if already customized.
- Add package.json scripts — if exists, add missing entries:
"ralph-tree": "bash scripts/ralph/ralph-tree.sh"
"ralph-audit": "bun scripts/ralph/ralph-audit.ts"
- Verify curl — required by ralph.sh for ntfy.sh notifications.
- Confirm setup — print summary: file status, NTFY_TOPIC, curl availability.
Output Format
json
{
"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": ["Criterion 1", "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 instance per iteration with no memory of previous work.
Right-sized: add a DB column, add a UI component, update a server action, add a filter.
Too big (split): "build the dashboard", "add auth", "refactor the API".
Rule of thumb: if you can't describe the change in 2-3 sentences, split it.
Story Ordering
Dependencies first: schema/migrations → backend logic → UI components → aggregation views.
Acceptance Criteria
Must be verifiable — something Ralph can CHECK.
Good: "Add
column with default 'pending'", "Filter has options: All, Active, Done", "Typecheck passes"
Bad: "Works correctly", "Good UX", "Handles edge cases"
Always include
as final criterion.
Add
for testable logic.
Add
"Verify in browser using dev-browser skill"
for UI changes.
Conversion Rules
- Each user story → one JSON entry
- IDs: sequential , , ...
- Priority: dependency order, then document order
- All stories: , empty
- branchName: kebab-case from feature name, prefixed
- Every story gets criterion
Splitting Large PRDs
Break big features into focused, independent stories. Example: "Add notification system" becomes: 1) notifications table, 2) notification service, 3) bell icon, 4) dropdown panel, 5) mark-as-read, 6) preferences page.
See
for a full input/output conversion example.
Archiving Previous Runs
Before writing new
, check for an existing one with a different
. If different and
has content beyond the header: archive to
archive/YYYY-MM-DD-feature-name/
, then reset
.
Checklist