doravidan/ralph

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:

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:

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

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

Archive previous prd.json if it exists:

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:

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

Reset progress.txt for new feature:

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:

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

# 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):

{
  "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": ""
    }
  ]
}