# Jlucaspains Sharp Cooking Web Prd Converter > Ralph PRD Converter - Skill: `tomevault-io/jlucaspains-sharp-cooking-web-prd-converter` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jlucaspains-sharp-cooking-web-prd-converter` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jlucaspains-sharp-cooking-web-prd-converter/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jlucaspains-sharp-cooking-web-prd-converter --- # Ralph PRD Converter Converts existing PRDs to the prd.yaml format that Ralph uses for autonomous execution. --- ## The Job Take a PRD (markdown file or text) and convert it to `.ralph/prd.yaml` in your scripts directory. --- ## Output Format ```yaml 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: '' ``` --- ## Story Size: The Number One Rule **Each story must be completable in ONE Ralph iteration (one context window).** Ralph spawns a fresh AI 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. --- ## Story Ordering: Dependencies First 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 --- ## Acceptance Criteria: Must Be Verifiable 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 playwright tests" ``` Frontend stories are NOT complete until visually verified. Ralph will use the playwright tests to navigate to the page, interact with the UI, and confirm changes work. --- ## Conversion Rules 1. **Each user story becomes one yaml 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 7. **Always add**: "Playwright tests pass" to story's acceptance criteria where UI changes are made. 8. **Never add**: User stories for testing, validation, or verification. **Always** include testing, validation, or verification in the acceptance criteria of the user story that made the change. --- ## Splitting Large PRDs 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. Tests should be acceptance criteria and **NOT** user stories. --- ## Example **Input PRD:** ```markdown # Task Status Feature Add ability to mark tasks with different statuses. ## Requirements - 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.yaml:** ```yaml 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 playwright tests 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 playwright tests 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 playwright tests priority: 4 passes: false notes: '' ``` --- ## Archiving Previous Runs **Before writing a new prd.yaml, check if there is an existing one from a different feature:** 1. Read the current `.ralph/prd.yaml` 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 `.ralph/prd.yaml` and `.ralph/progress.txt` to archive - Reset `progress.txt` with fresh header **The ralph CLI script handles this automatically** when you run it, but if you are manually updating prd.yaml between runs, archive first. --- ## Checklist Before Saving Before writing prd.yaml, verify: - [ ] **Previous run archived** (if prd.yaml exists with different branchName, archive it first) - [ ] 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 using playwright tests" as criterion - [ ] Acceptance criteria are verifiable (not vague) - [ ] No story depends on a later story --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jlucaspains) — claim your Tome and manage your conversions.