1---
2name: ralph-convert-prd
3description: Converts Product Requirements Documents into prd.json format for the Ralph autonomous agent system. Use when preparing PRDs for Ralph execution, breaking down features into atomic user stories, or when the user mentions Ralph, prd.json, or autonomous agent workflows.
4model: claude-opus-4-5
5context: fork
6metadata:
7 source: https://skillmd.com/skills/cfircoo/ralph-convert-prd
8---
9
10<objective>
11Transform 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. Each story must include real runtime verification commands.
12</objective>
13
14<quick_start>
151. Read the user's PRD or feature requirements
162. Read SPEC.md if available (for verification environment info)
173. Break down into atomic user stories (one context window each)
184. Classify each story with `storyType`
195. Generate `verificationCommands` with real runtime checks
206. Set `blockedBy` dependencies
217. Order stories by dependency (schema → backend → UI → dashboard)
228. Output valid `tasks/prd.json`
23</quick_start>
24
25<essential_principles>
26<principle name="story_size">
27**Critical Rule**: Each story must be completable in ONE Ralph iteration (one context window).
28
29Stories that are too large cause the LLM to run out of context before completion, resulting in broken code.
30
31**Right-sized stories**:
32- Add a database column
33- Create a UI component
34- Update server actions
35- Implement a filter
36
37**Too large (split these)**:
38- Build entire dashboards
39- Add authentication systems
40- Refactor entire APIs
41</principle>
42
43<principle name="story_ordering">
44Stories must execute sequentially without forward dependencies:
45
461. Schema/database changes
472. Server actions and backend logic
483. UI components
494. Dashboard/summary views
50
51Never reference something that doesn't exist yet.
52</principle>
53
54<principle name="acceptance_criteria">
55Each criterion must be verifiable and specific. Avoid vague language.
56
57**Good criteria**:
58- "Add status column with values: 'pending' | 'in_progress' | 'done'"
59- "Filter dropdown includes: All, Active, Completed"
60- "Clicking delete shows confirmation dialog"
61
62**Bad criteria** (too vague):
63- "Works correctly"
64- "Good UX"
65- "Handles edge cases"
66</principle>
67
68<principle name="mandatory_criteria">
69Every story MUST include: `"Typecheck passes"`
70
71UI-focused stories MUST also include: `"Verify in browser using Playwright e2e test"`
72</principle>
73
74<principle name="real_verification">
75Every story MUST include `verificationCommands` with real runtime checks — not just static analysis.
76
77**By storyType:**
78
79| storyType | Required verification | Example |
80|-----------|----------------------|---------|
81| `database` | Run migration + query DB to confirm schema | `prisma migrate deploy`, SQL query for new column |
82| `backend` | Run tests + curl endpoint with real data | `curl -s http://localhost:3000/api/...` |
83| `api` | curl endpoint, check status code and response body | `curl -s -w '%{http_code}' ...` |
84| `frontend` | Playwright e2e test that interacts with real UI | `npx playwright test tests/e2e/...` |
85| `infra` | Health check, config validation, service startup | `curl -s http://localhost:3000/health` |
86| `test` | Run the test suite | `npm test` / `pytest` |
87
88Static checks (typecheck) are always included as baseline. Runtime validation is **additionally required**.
89</principle>
90</essential_principles>
91
92<output_format>
93```json
94{
95 "project": "[Project Name]",
96 "branchName": "ralph/[feature-name-kebab-case]",
97 "description": "[Feature description]",
98 "testCommands": {
99 "unit": "npm test",
100 "integration": "npm run test:integration",
101 "e2e": "npx playwright test",
102 "typecheck": "npm run typecheck"
103 },
104 "userStories": [
105 {
106 "id": "US-001",
107 "title": "[Story title]",
108 "description": "As a [user], I want [feature] so that [benefit]",
109 "storyType": "database",
110 "acceptanceCriteria": [
111 "Specific criterion 1",
112 "Specific criterion 2",
113 "Typecheck passes"
114 ],
115 "verificationCommands": [
116 { "command": "npm run typecheck", "expect": "exit_code:0" },
117 { "command": "curl -s http://localhost:3000/api/tasks | jq length", "expect": "not_empty" }
118 ],
119 "status": "pending",
120 "priority": 1,
121 "attempts": 0,
122 "maxAttempts": 3,
123 "notes": "",
124 "blockedBy": [],
125 "docsToUpdate": ["README.md"],
126 "completedAt": null,
127 "lastAttemptLog": ""
128 }
129 ]
130}
131```
132
133**Field requirements**:
134- `id`: Sequential US-001, US-002, etc.
135- `title`: Short, descriptive action
136- `description`: User story format (As a... I want... so that...)
137- `storyType`: One of `"backend"` | `"frontend"` | `"database"` | `"api"` | `"infra"` | `"test"`
138- `acceptanceCriteria`: Array of specific, verifiable criteria
139- `verificationCommands`: Array of `{command, expect}` with real runtime checks
140- `status`: Always `"pending"` initially
141- `priority`: Execution order (1 = first)
142- `attempts`: Always `0` initially
143- `maxAttempts`: Default `3` (increase for complex stories)
144- `notes`: Empty string initially
145- `blockedBy`: Array of story IDs that must be `"done"` first
146- `docsToUpdate`: Array of file paths to documentation that must be updated when story is done (e.g., `"README.md"`, `"docs/api.md"`, `"CHANGELOG.md"`)
147- `completedAt`: Always `null` initially
148- `lastAttemptLog`: Empty string initially
149
150**Expect matchers for verificationCommands:**
151- `exit_code:0` — command exits with code 0
152- `exit_code:N` — command exits with specific code N
153- `contains:STRING` — stdout contains STRING
154- `not_empty` — stdout is non-empty
155- `matches:REGEX` — stdout matches regex pattern
156</output_format>
157
158<workflow>
1591. **Understand the PRD**: Read the full requirements document or feature request
1602. **Read SPEC.md**: If available, extract verification environment info (dev server URL, DB type, test runners, commands). Use this to populate the root-level `testCommands` object
1613. **Identify components**: List all database changes, backend logic, UI elements
1624. **Decompose into stories**: Break each component into atomic, one-iteration tasks
1635. **Classify storyType**: Assign `database`, `backend`, `api`, `frontend`, `infra`, or `test` to each story
1646. **Order by dependency**: Schema first, then backend, then UI, then dashboards
1657. **Set blockedBy**: Each story should list IDs of stories it depends on
1668. **Write acceptance criteria**: Make each criterion specific and verifiable
1679. **Generate verificationCommands**: Add real runtime checks per storyType (curl, Playwright, DB queries)
16810. **Add mandatory criteria**: Ensure every story has "Typecheck passes"
16911. **Generate tasks/prd.json**: Output the complete JSON structure to `tasks/prd.json`
17012. **Run pre-save checklist**: Verify all requirements before finalizing
171</workflow>
172
173<pre_save_checklist>
174Before outputting the final prd.json, verify:
175
176- [ ] Previous runs archived (if applicable)
177- [ ] Each story completable in one iteration
178- [ ] Each story has a `storyType` assigned
179- [ ] Stories ordered by dependency (no forward references)
180- [ ] `blockedBy` dependencies are set correctly
181- [ ] All stories include "Typecheck passes" in acceptanceCriteria
182- [ ] UI stories include Playwright verification
183- [ ] Every story has `verificationCommands` with at least one runtime check
184- [ ] Acceptance criteria are verifiable, not vague
185- [ ] No story depends on later stories
186- [ ] `docsToUpdate` lists relevant docs for each story
187- [ ] `status` is `"pending"`, `attempts` is `0`, `maxAttempts` is set
188</pre_save_checklist>
189
190<examples>
191<example name="database_story">
192```json
193{
194 "id": "US-001",
195 "title": "Add task status column to database",
196 "description": "As a developer, I want a status column on tasks so that we can track task progress",
197 "storyType": "database",
198 "acceptanceCriteria": [
199 "Add status column to tasks table with type enum('pending', 'in_progress', 'done')",
200 "Default value is 'pending'",
201 "Migration runs without errors",
202 "Typecheck passes"
203 ],
204 "verificationCommands": [
205 { "command": "npx prisma migrate deploy", "expect": "exit_code:0" },
206 { "command": "npx prisma db execute --stdin <<< \"SELECT column_name FROM information_schema.columns WHERE table_name='tasks' AND column_name='status'\"", "expect": "contains:status" },
207 { "command": "npm run typecheck", "expect": "exit_code:0" }
208 ],
209 "status": "pending",
210 "priority": 1,
211 "attempts": 0,
212 "maxAttempts": 3,
213 "notes": "",
214 "blockedBy": [],
215 "docsToUpdate": ["README.md"],
216 "completedAt": null,
217 "lastAttemptLog": ""
218}
219```
220</example>
221
222<example name="api_story">
223```json
224{
225 "id": "US-002",
226 "title": "Create task CRUD API endpoints",
227 "description": "As a developer, I want REST endpoints for tasks so that the frontend can manage tasks",
228 "storyType": "api",
229 "acceptanceCriteria": [
230 "GET /api/tasks returns array of tasks",
231 "POST /api/tasks creates a new task and returns 201",
232 "PATCH /api/tasks/:id updates task and returns 200",
233 "DELETE /api/tasks/:id removes task and returns 204",
234 "Typecheck passes"
235 ],
236 "verificationCommands": [
237 { "command": "npm run typecheck", "expect": "exit_code:0" },
238 { "command": "npm test -- --grep 'tasks API'", "expect": "exit_code:0" },
239 { "command": "curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/api/tasks", "expect": "contains:200" },
240 { "command": "curl -s -X POST http://localhost:3000/api/tasks -H 'Content-Type: application/json' -d '{\"title\":\"test task\"}' -o /dev/null -w '%{http_code}'", "expect": "contains:201" }
241 ],
242 "status": "pending",
243 "priority": 2,
244 "attempts": 0,
245 "maxAttempts": 3,
246 "notes": "",
247 "blockedBy": ["US-001"],
248 "docsToUpdate": ["README.md", "docs/api.md"],
249 "completedAt": null,
250 "lastAttemptLog": ""
251}
252```
253</example>
254
255<example name="ui_story">
256```json
257{
258 "id": "US-003",
259 "title": "Add status filter dropdown to task list",
260 "description": "As a user, I want to filter tasks by status so that I can focus on relevant tasks",
261 "storyType": "frontend",
262 "acceptanceCriteria": [
263 "Filter dropdown appears above task list",
264 "Options: All, Pending, In Progress, Done",
265 "Selecting option filters displayed tasks",
266 "Filter persists on page refresh",
267 "Typecheck passes",
268 "Verify in browser using Playwright e2e test"
269 ],
270 "verificationCommands": [
271 { "command": "npm run typecheck", "expect": "exit_code:0" },
272 { "command": "npx playwright test tests/e2e/task-filter.spec.ts", "expect": "exit_code:0" }
273 ],
274 "status": "pending",
275 "priority": 3,
276 "attempts": 0,
277 "maxAttempts": 3,
278 "notes": "",
279 "blockedBy": ["US-002"],
280 "docsToUpdate": ["README.md"],
281 "completedAt": null,
282 "lastAttemptLog": ""
283}
284```
285</example>
286</examples>
287
288<success_criteria>
289Conversion is complete when:
290
291- [ ] All features from PRD are captured as user stories
292- [ ] Each story is atomic (one context window)
293- [ ] Each story has a `storyType` assigned
294- [ ] Stories are properly ordered by dependency with `blockedBy` set
295- [ ] All acceptance criteria are specific and verifiable
296- [ ] Mandatory criteria ("Typecheck passes") present on all stories
297- [ ] Every story has `verificationCommands` with real runtime checks
298- [ ] UI stories include Playwright verification
299- [ ] Valid JSON structure with all required fields
300- [ ] Pre-save checklist passes
301</success_criteria>