PRD to JSON Conversion Skill

Expert guidance for converting PRDs to Ralf's executable JSON format.

When to Use

• •User has a PRD and wants to run Ralf
• •User mentions "convert to json" or "prd.json"
• •After generating a PRD, to prepare for execution

JSON Schema

{
  "project": "string",
  "branchName": "ralf/feature-name",
  "description": "string",
  "settings": {
    "tddRequired": true,
    "autoPush": true,
    "executionMode": "sequential",
    "evaluatorEnabled": true,
    "allowReorder": true,
    "evaluateEveryNIterations": 3,
    "maxRetries": 3
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "string",
      "description": "As a..., I want..., so that...",
      "acceptanceCriteria": ["string"],
      "priority": 1,
      "passes": false,
      "notes": "",
      "targetFiles": ["src/path/to/file.ts"],
      "specReference": "FR-1, FR-2",
      "metrics": {
        "startedAt": null,
        "completedAt": null,
        "durationMs": null,
        "tokensConsumed": null,
        "attempts": []
      }
    }
  ]
}

Conversion Rules

1. •Branch Naming: ralf/ prefix + kebab-case feature name
2. •Story IDs: Sequential US-001, US-002, etc.
3. •Priority: Based on dependency order (1 = first to implement)
4. •Initial State: All passes: false, empty notes
5. •Acceptance Criteria: Always end with "Typecheck passes"
6. •targetFiles: Scan codebase to identify likely files to create/modify
7. •specReference: Link to functional requirements (e.g., "FR-1, FR-2")
8. •metrics: Initialize with null values and empty attempts array
9. •settings: Include project-level execution preferences

Dependency Ordering

Priority must respect dependencies:

1. •Database/schema changes
2. •Backend logic/server actions
3. •UI components
4. •Integration/dashboard views

A story cannot depend on a later (higher priority number) story.

Story Size Validation

Before conversion, validate each story is small enough:

• •Can be described in 2-3 sentences
• •Touches limited number of files
• •Has clear start and end point
• •No "and then also..." scope creep

Archive Check

Before overwriting existing .ralf/prd.json:

1. •Check if existing .ralf/prd.json has different branchName
2. •If yes, archive to .ralf/archive/YYYY-MM-DD-feature-name/
3. •Include both .ralf/prd.json and .ralf/progress.txt

Strong Linkage (FR-03)

Each story should have clear linkage to:

targetFiles

Identify files that will be created or modified:

• •Scan existing codebase structure
• •Consider component/module naming patterns
• •Include test files if TDD is enabled

"targetFiles": [
  "src/components/LoginForm.tsx",
  "src/hooks/useAuth.ts",
  "src/components/__tests__/LoginForm.test.tsx"
]

specReference

Link to functional requirements from the PRD:

• •Reference FR numbers for traceability
• •Helps verify all requirements are covered
• •Enables requirement-to-implementation mapping

"specReference": "FR-1, FR-3, NFR-2"

Output

Save to: .ralf/prd.json

Create directory if needed: mkdir -p .ralf