Ralph Convert Prd

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:

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

Field requirements:

• id: Sequential US-001, US-002, etc.
• title: Short, descriptive action
• description: User story format (As a... I want... so that...)
• storyType: One of "backend" | "frontend" | "database" | "api" | "infra" | "test"
• acceptanceCriteria: Array of specific, verifiable criteria
• verificationCommands: Array of {command, expect} with real runtime checks
• status: Always "pending" initially
• priority: Execution order (1 = first)
• attempts: Always 0 initially
• maxAttempts: Default 3 (increase for complex stories)
• notes: Empty string initially
• blockedBy: Array of story IDs that must be "done" first
• docsToUpdate: Array of file paths to documentation that must be updated when story is done (e.g., "README.md", "docs/api.md", "CHANGELOG.md")
• completedAt: Always null initially
• lastAttemptLog: Empty string initially

Expect matchers for verificationCommands:

• exit_code:0 — command exits with code 0
• exit_code:N — command exits with specific code N
• contains:STRING — stdout contains STRING
• not_empty — stdout is non-empty
• matches:REGEX — stdout matches regex pattern

Before outputting the final prd.json, verify:

• Previous runs archived (if applicable)
• Each story completable in one iteration
• Each story has a storyType assigned
• Stories ordered by dependency (no forward references)
• blockedBy dependencies are set correctly
• All stories include "Typecheck passes" in acceptanceCriteria
• UI stories include Playwright verification
• Every story has verificationCommands with at least one runtime check
• Acceptance criteria are verifiable, not vague
• No story depends on later stories
• docsToUpdate lists relevant docs for each story
• status is "pending", attempts is 0, maxAttempts is set

• All features from PRD are captured as user stories
• Each story is atomic (one context window)
• Each story has a storyType assigned
• Stories are properly ordered by dependency with blockedBy set
• All acceptance criteria are specific and verifiable
• Mandatory criteria ("Typecheck passes") present on all stories
• Every story has verificationCommands with real runtime checks
• UI stories include Playwright verification
• Valid JSON structure with all required fields
• Pre-save checklist passes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.