Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

The prd.json file is Ralph’s structured format for product requirement documents. It breaks features into small, autonomous user stories that Ralph can implement one at a time.

​
File Structure

{
  "project": "string",
  "branchName": "string",
  "description": "string",
  "userStories": []
}

​
Top-Level Fields

​
project
string
required
The name of the project or application.Example: "MyApp"
​
branchName
string
required
Git branch name for this feature. Must be prefixed with ralph/ and use kebab-case.Example: "ralph/task-priority"Pattern: ralph/[feature-name-kebab-case]
​
description
string
required
High-level description of the feature being implemented.Example: "Task Priority System - Add priority levels to tasks"
​
userStories
array
required
Array of user story objects. Stories execute in priority order.

​
User Story Object

Each story in the userStories array has the following structure:
​
id
string
required
Unique identifier for the story. Use sequential format.Format: US-001, US-002, US-003, etc.
​
title
string
required
Brief, descriptive title for the user story.Example: "Add priority field to database"
​
description
string
required
User story in standard format explaining the “who, what, why.”Format: "As a [user type], I want [feature] so that [benefit]"Example: "As a developer, I need to store task priority so it persists across sessions."
​
acceptanceCriteria
string[]
required
Array of verifiable acceptance criteria. Must be checkable, not vague.Required criteria:
  • Always include: "Typecheck passes"
  • For UI stories, include: "Verify in browser using dev-browser skill"
  • For testable logic, include: "Tests pass"
Example:
[
  "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')",
  "Generate and run migration successfully",
  "Typecheck passes"
]
​
priority
number
required
Execution order. Lower numbers execute first. Must account for dependencies.Values: 1, 2, 3, etc.Ordering rule: Dependencies first (schema → backend → UI)
​
passes
boolean
required
Whether the story has been successfully implemented.Initial value: falseUpdated by: Ralph sets to true after successful implementation and commit
​
notes
string
required
Additional notes or context. Typically empty initially.Initial value: ""

​
Complete Example

{
  "project": "MyApp",
  "branchName": "ralph/task-priority",
  "description": "Task Priority System - Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority so it persists across sessions.",
      "acceptanceCriteria": [
        "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display priority indicator on task cards",
      "description": "As a user, I want to see task priority at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored priority badge (red=high, yellow=medium, gray=low)",
        "Priority visible without hovering or clicking",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add priority selector to task edit",
      "description": "As a user, I want to change a task's priority when editing it.",
      "acceptanceCriteria": [
        "Priority dropdown in task edit modal",
        "Shows current priority as selected",
        "Saves immediately on selection change",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by priority",
      "description": "As a user, I want to filter the task list to see only high-priority items.",
      "acceptanceCriteria": [
        "Filter dropdown with options: All | High | Medium | Low",
        "Filter persists in URL params",
        "Empty state message when no tasks match filter",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ]
}

​
Story Sizing Guidelines

Each story must be completable in ONE Ralph iteration (one context window).Ralph spawns a fresh AI instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing.

​
Right-Sized Stories

  • Add a database column and migration
  • Add a UI component to an existing page
  • Update a server action with new logic
  • Add a filter dropdown to a list

​
Too Big (Split These)

  • “Build the entire dashboard” → Split into: schema, queries, UI components, filters
  • “Add authentication” → Split into: schema, middleware, login UI, session handling
  • “Refactor the API” → Split into one story per endpoint or pattern
Rule of thumb: If you cannot describe the change in 2-3 sentences, it’s too big.

​
Story Ordering Rules

Stories execute in priority order. Earlier stories must not depend on later ones.

​
Correct Order

  1. Schema/database changes (migrations)
  2. Server actions / backend logic
  3. UI components that use the backend
  4. Dashboard/summary views that aggregate data

​
Wrong Order

  1. UI component (depends on schema that doesn’t exist yet) ❌
  2. Schema change

​
Acceptance Criteria Best Practices

Each criterion must be verifiable, not vague.

​
Good Criteria (Verifiable)

  • “Add status column to tasks table with default ‘pending’”
  • “Filter dropdown has options: All, Active, Completed”
  • “Clicking delete shows confirmation dialog”
  • “Typecheck passes”
  • “Tests pass”

​
Bad Criteria (Vague)

  • “Works correctly” ❌
  • “User can do X easily” ❌
  • “Good UX” ❌
  • “Handles edge cases” ❌

​
Required Criteria

Always include as final criterion: 
"Typecheck passes"
For UI stories, also include: 
"Verify in browser using dev-browser skill"
For testable logic, also include: 
"Tests pass"
Frontend stories are NOT complete until visually verified in the browser.

​
Archiving Previous Runs

Before writing a new prd.json, check if there’s an existing one from a different feature:
  1. Read the current prd.json if it exists
  2. Check if branchName differs from the new feature’s branch name
  3. If different AND progress.txt has content beyond the header:
    • Create archive folder: archive/YYYY-MM-DD-feature-name/
    • Copy current prd.json and progress.txt to archive
    • Reset progress.txt with fresh header
The ralph.sh script handles archiving automatically when you run it.

​
Conversion Checklist

Before saving prd.json, verify:
  • Previous run archived (if prd.json exists with different branchName)
  • Each story is completable in one iteration (small enough)
  • Stories are ordered by dependency (schema → backend → UI)
  • Every story has “Typecheck passes” as criterion
  • UI stories have “Verify in browser using dev-browser skill” as criterion
  • Acceptance criteria are verifiable (not vague)
  • No story depends on a later story
  • All stories have passes: false initially
  • All stories have empty notes initially

Build docs developers (and LLMs) love

Get started for freeTalk to us