Ralph Skill

Convert PRD Markdown files to prd.json format for RALPH automation.

Trigger

This skill activates when the user asks to:

•Convert a PRD to JSON
•Prepare a PRD for RALPH
•Create prd.json from a PRD file

Process

Step 1: Read the PRD

Read the specified PRD Markdown file:

bash

cat tasks/prd-[feature-name].md

Step 2: Extract Information

Parse the PRD to extract:

•Project name (from title)
•Description (from overview)
•
User stories with:
- •ID (US-001, US-002, etc.)
- •Title
- •Description (As a... I want... So that...)
- •Acceptance criteria
- •Priority

Step 3: Generate prd.json

Create the JSON structure:

json

{
  "project": "[Feature Name]",
  "branchName": "ralph/[feature-slug]",
  "description": "[Overview text]",
  "createdAt": "[Today's date]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "[Full story description]",
      "acceptanceCriteria": [
        "[Criterion 1]",
        "[Criterion 2]",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Step 4: Validate and Save

Before saving, validate:

•Every story has "Typecheck passes" in criteria
•Stories are ordered by priority (dependencies first)
•Each story is small enough for one iteration
•Branch name follows ralph/[feature-slug] format

Archive previous prd.json if it exists:

bash

if [ -f prd.json ]; then
  mkdir -p archive/$(date +%Y-%m-%d)
  cp prd.json archive/$(date +%Y-%m-%d)/
  cp progress.txt archive/$(date +%Y-%m-%d)/ 2>/dev/null || true
fi

Save the new prd.json:

bash

cat > prd.json << 'EOF'
[JSON content]
EOF

Reset progress.txt for new feature:

bash

cat > progress.txt << 'EOF'
# Progress Log - ralph/[feature-slug]

## Codebase Patterns
(Patterns will be added as they are discovered)

---

EOF

Rules for Story Conversion

1. Story Sizing

If a PRD story is too large, split it:

•Data model → separate story
•Backend logic → separate story
•API endpoint → separate story
•UI component → separate story
•Tests → integrated into each story

2. Priority Assignment

Assign priorities based on dependencies:

•Priority 1: Schema/data models (foundation)
•Priority 2: Core business logic
•Priority 3: API/backend endpoints
•Priority 4: UI components
•Priority 5: Polish/optimization

3. Required Criteria

Always ensure these criteria exist:

•All stories: "Typecheck passes"
•Backend stories: "Tests pass"
•UI stories: "Verify in browser"
•API stories: "Response format is correct"

4. Branch Naming

Convert feature name to slug:

•"User Authentication" → ralph/user-authentication
•"Dark Mode Toggle" → ralph/dark-mode-toggle
•Use lowercase, replace spaces with hyphens

Output

After conversion:

code

Converted PRD to prd.json

Summary:
- Project: [Feature Name]
- Branch: ralph/[feature-slug]
- Stories: [N] total

Stories:
1. US-001: [Title] (Priority 1)
2. US-002: [Title] (Priority 2)
...

Next steps:
1. Review prd.json for accuracy
2. Start RALPH: ./scripts/ralph/ralph.sh 20
3. Monitor progress in progress.txt

Example Conversion

Input (tasks/prd-dark-mode.md):

markdown

# PRD: Dark Mode Toggle

## Overview
Add a dark mode toggle to the application settings.

## User Stories

### US-001: Create theme context
**As a** developer
**I want** a theme context provider
**So that** components can access the current theme

**Acceptance Criteria:**
- [ ] ThemeContext created with light/dark values
- [ ] ThemeProvider wraps the app
- [ ] useTheme hook exported
- [ ] Typecheck passes

Output (prd.json):

json

{
  "project": "Dark Mode Toggle",
  "branchName": "ralph/dark-mode-toggle",
  "description": "Add a dark mode toggle to the application settings.",
  "createdAt": "2026-01-19",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create theme context",
      "description": "As a developer, I want a theme context provider so that components can access the current theme",
      "acceptanceCriteria": [
        "ThemeContext created with light/dark values",
        "ThemeProvider wraps the app",
        "useTheme hook exported",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}