ralph-convert-prd

<quick_start>

1. Read the user's PRD or feature requirements
2. Read SPEC.md if available (for verification environment info)
3. Break down into atomic user stories (one context window each)
4. Classify each story with storyType
5. Generate verificationCommands with real runtime checks
6. Set blockedBy dependencies
7. Order stories by dependency (schema → backend → UI → dashboard)
8. Output valid tasks/prd.json </quick_start>

<essential_principles> Critical Rule: Each story must be completable in ONE Ralph iteration (one context window).

Stories that are too large cause the LLM to run out of context before completion, resulting in broken code.

Right-sized stories:

• Add a database column
• Create a UI component
• Update server actions
• Implement a filter

Too large (split these):

• Build entire dashboards
• Add authentication systems
• Refactor entire APIs

1. Schema/database changes
2. Server actions and backend logic
3. UI components
4. Dashboard/summary views

Never reference something that doesn't exist yet.

Good criteria:

• "Add status column with values: 'pending' | 'in_progress' | 'done'"
• "Filter dropdown includes: All, Active, Completed"
• "Clicking delete shows confirmation dialog"

Bad criteria (too vague):

• "Works correctly"
• "Good UX"
• "Handles edge cases"

UI-focused stories MUST also include: "Verify in browser using Playwright e2e test"

By storyType:

storyType	Required verification	Example
database	Run migration + query DB to confirm schema	prisma migrate deploy, SQL query for new column
backend	Run tests + curl endpoint with real data	curl -s http://localhost:3000/api/...
api	curl endpoint, check status code and response body	curl -s -w '%{http_code}' ...
frontend	Playwright e2e test that interacts with real UI	npx playwright test tests/e2e/...
infra	Health check, config validation, service startup	curl -s http://localhost:3000/health
test	Run the test suite	npm test / pytest

Static checks (typecheck) are always included as baseline. Runtime validation is additionally required. </essential_principles>

<output_format>

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description]",
  "testCommands": {
    "unit": "npm test",
    "integration": "npm run test:integration",
    "e2e": "npx playwright test",
    "typecheck": "npm run typecheck"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "storyType": "database",
      "acceptanceCriteria": [
        "Specific criterion 1",
        "Specific criterion 2",
        "Typecheck passes"
      ],
      "verificationCommands": [
        { "command": "npm run typecheck", "expect": "exit_code:0" },
        { "command": "curl -s http://localhost:3000/api/tasks | jq length", "expect": "not_empty" }
      ],
      "status": "pending",
      "priority": 1,
      "attempts": 0,
      "maxAttempts": 3,
      "notes": "",
      "blockedBy": [],
      "docsToUpdate": ["README.md"],
      "completedAt": null,
      "lastAttemptLog": ""
    }
  ]
}