Agent skill

prd-to-ralph

Use when converting PRD/requirements into JSON format for Ralph Wiggum autonomous loops. Extracts user stories, orders by dependency (schema first, then backend, then UI, then dashboard), auto-adds standard criteria (typecheck, build, lint, tests), outputs structured JSON ready for autonomous iteration.

View SKILL.md on GitHub Repository
Stars 6
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/galihcitta/dotclaudeskills/tree/main/skills/prd-to-ralph

SKILL.md

PRD to Ralph JSON Converter

Convert PRD/requirements into structured JSON optimized for Ralph Wiggum autonomous coding loops.

Overview

Ralph Wiggum workflows iterate autonomously toward success criteria. This skill converts human-readable PRDs into machine-parseable JSON with:

  • Dependency-ordered user stories (schema before API before UI)
  • Testable acceptance criteria
  • Standard quality gates on every story

When to Use

  • Converting PRD/requirements for Ralph autonomous workflow
  • Preparing features for autonomous iteration
  • Need structured JSON from prose requirements

When NOT to Use

  • Already have JSON in correct format
  • Single-task changes (no stories needed)
  • Non-coding requirements

Output Schema

json
{
  "project": "Project Name",
  "branchName": "ralph/feature-name-kebab-case",
  "description": "Feature description from PRD",
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion from PRD",
        "Another criterion",
        "Typecheck passes",
        "Build succeeds",
        "No lint errors",
        "Tests pass"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Workflow

Phase 1: Extract Project Metadata

  1. Project name: Use PRD title or main heading
  2. Branch name: Convert to kebab-case with ralph/ prefix
  3. Description: First paragraph or intro section

Phase 2: Identify User Stories

Extract stories from:

  • Explicit "User Story" sections
  • Numbered requirements
  • Feature bullet points
  • Prose paragraphs describing functionality

For each story, create:

  • Unique ID (US-001, US-002, etc.)
  • Title (short, descriptive)
  • Description (user story format: As a... I want... so that...)
  • Acceptance criteria from PRD content

Phase 3: Classify Story Layer

CRITICAL: Classify each story into exactly one layer:

Layer Priority Keywords/Patterns
Schema/Database 1 table, migration, schema, column, field, index, foreign key, database, model definition
Backend/API 2 endpoint, API, route, controller, service, handler, REST, GraphQL, server action
Frontend/UI 3 component, page, button, form, modal, UI, display, render, click, user interface
Dashboard/Admin 4 dashboard, admin, metrics, analytics, reports, monitoring, management

Detection rules:

  • Schema: Creates/modifies database structure
  • Backend: Implements server logic or API endpoints
  • Frontend: User-facing interface components
  • Dashboard: Admin/analytics views (depends on everything else)

Phase 4: Order by Dependency

MANDATORY: Reorder stories so dependencies come first.

Priority 1: Schema/Database stories
Priority 2: Backend/API stories
Priority 3: Frontend/UI stories
Priority 4: Dashboard/Admin stories

Within same layer: Maintain original PRD order.

NEVER output stories in PRD order if that violates dependency order.

Phase 5: Add Standard Criteria

MANDATORY: Append these 4 criteria to EVERY story:

json
"acceptanceCriteria": [
  "...criteria from PRD...",
  "Typecheck passes",
  "Build succeeds",
  "No lint errors",
  "Tests pass"
]

No exceptions. Every story gets all 4 standard criteria.

Phase 6: Generate JSON

Output valid JSON with:

  • All required fields populated
  • passes: false for all stories
  • notes: "" empty string
  • Stories sorted by priority (1 → 2 → 3 → 4)

Phase 7: Validate

Before outputting, verify:

  • Stories ordered by dependency (schema → API → UI → dashboard)
  • All 4 standard criteria present on every story
  • Valid JSON syntax
  • Branch name is kebab-case
  • All required fields present

Dependency Detection Patterns

Schema/Database (Priority 1)

- "create table", "add column", "migration"
- "database schema", "data model"
- "foreign key", "index", "constraint"
- "notifications table", "users table"
- Any mention of table structure or fields

Backend/API (Priority 2)

- "API endpoint", "REST", "GraphQL"
- "GET/POST/PATCH/DELETE /api/"
- "controller", "handler", "service"
- "server action", "backend logic"
- "authentication", "authorization" (server-side)

Frontend/UI (Priority 3)

- "component", "page", "view"
- "button", "form", "modal", "dropdown"
- "click", "hover", "display"
- "header", "footer", "sidebar"
- "user interface", "UI"

Dashboard/Admin (Priority 4)

- "dashboard", "admin panel"
- "metrics", "analytics", "reports"
- "monitoring", "management view"
- "aggregate", "statistics"

Common Mistakes

Mistake Fix
Keep PRD order Always reorder by dependency
Skip standard criteria Add all 4 to every story
Same priority for all Use layer-based priority (1-4)
Missing passes/notes fields Always include with false/""
Space in branch name Use kebab-case only

Red Flags - STOP and Fix

  • UI story has priority 1 (should be 3+)
  • Schema story has priority 3+ (should be 1)
  • Missing "Typecheck passes" criterion
  • Stories not sorted by priority number
  • Multiple stories with same priority across different layers

Example Transformation

Input PRD:

markdown
# Notification System

## Stories
1. Notification Bell UI - show bell with unread count
2. Notification API - GET/POST endpoints
3. Notification Schema - create notifications table

Output JSON:

json
{
  "project": "Notification System",
  "branchName": "ralph/notification-system",
  "description": "Notification system for real-time alerts",
  "userStories": [
    {
      "id": "US-001",
      "title": "Notification Schema",
      "description": "As a developer, I want a notifications table so that notification data can be persisted",
      "acceptanceCriteria": [
        "Notifications table created with required fields",
        "Typecheck passes",
        "Build succeeds",
        "No lint errors",
        "Tests pass"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Notification API",
      "description": "As a developer, I want API endpoints so that the frontend can access notifications",
      "acceptanceCriteria": [
        "GET endpoint returns user notifications",
        "POST endpoint creates notifications",
        "Typecheck passes",
        "Build succeeds",
        "No lint errors",
        "Tests pass"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Notification Bell UI",
      "description": "As a user, I want a notification bell so that I can see my unread notifications",
      "acceptanceCriteria": [
        "Bell icon displayed in header",
        "Unread count badge shown",
        "Typecheck passes",
        "Build succeeds",
        "No lint errors",
        "Tests pass"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    }
  ]
}

Note: Stories reordered from PRD (UI→API→Schema) to dependency order (Schema→API→UI).

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

galihcitta/dotclaudeskills

troubleshooting-kubernetes

Diagnoses and fixes Kubernetes issues with interactive remediation. Use when pods crash (CrashLoopBackOff, OOMKilled), services unreachable (502/503, empty endpoints), deployments stuck (ImagePullBackOff, pending). Also use when tempted to run kubectl fix commands directly without presenting options, or when user says "just fix it" for K8s issues.

6 0
Explore
galihcitta/dotclaudeskills

generating-adrs

Use when PRD/TRD contains architectural decisions to document - extracts decisions from refined requirements (architecture choices, data model decisions, API patterns, technology selections, integration strategies, reuse patterns) and generates MADR-format ADRs. One ADR per decision point. Also use when asked to document decisions, create decision records, or retrospectively capture architectural choices.

6 0
Explore
galihcitta/dotclaudeskills

code-reviewer

Comprehensive code review skill for TypeScript, JavaScript, Python, Swift, Kotlin, Go. Includes automated code analysis, best practice checking, security scanning, and review checklist generation. Use when reviewing pull requests, providing code feedback, identifying issues, or ensuring code quality standards.

6 0
Explore
galihcitta/dotclaudeskills

detecting-ai-code

Use when auditing code for AI authorship, reviewing acquisitions/contractors, verifying academic integrity, or during code review - provides systematic tiered framework for detecting fully AI-generated AND AI-assisted code patterns with confidence scoring

6 0
Explore
galihcitta/dotclaudeskills

refining-requirements

Use when PRD is prose-heavy, ambiguous, has scattered file paths, missing API contracts, or says "similar to X" without explanation. Transforms rough requirements into implementation-ready specs. Auto-detects tech stack, validates file paths (EXISTS/CREATE/VERIFY markers), handles greenfield and multi-stack projects. Do NOT use for simple bug fixes, typos, or already-structured Jira tickets with clear file paths and acceptance criteria.

6 0
Explore
galihcitta/dotclaudeskills

interviewing-plans

Use when a plan, PRD, or spec has vague requirements, undefined terms, or missing details - conducts structured interview using AskUserQuestion to surface hidden assumptions, challenge ambiguities, and produce implementation-ready specs. Also use proactively when encountering plans that say things like "make it faster" or "improve UX" without concrete definitions.

6 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results