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.

​
Right-Sizing Stories

The most important rule for successful Ralph execution: each story must be completable in one iteration (one context window).

​
Why Story Size Matters

Ralph spawns a fresh AI instance for each iteration with no memory of previous work except:
  • Git history
  • progress.txt learnings
  • prd.json status
If a story is too large, the LLM runs out of context before finishing and produces broken code. This compounds across iterations and breaks your CI.

​
Right-Sized Stories

Each story should be describable in 2-3 sentences:
1

Database changes

Add a database column and migration
{
  "id": "US-001",
  "title": "Add status field to tasks table",
  "acceptanceCriteria": [
    "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
    "Generate and run migration successfully",
    "Typecheck passes"
  ]
}
2

UI components

Add a UI component to an existing page
{
  "id": "US-002",
  "title": "Display status badge on task cards",
  "acceptanceCriteria": [
    "Each task card shows colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ]
}
3

Backend logic

Update a server action with new logic
{
  "id": "US-003",
  "title": "Add status toggle to task list rows",
  "acceptanceCriteria": [
    "Each row has status dropdown or toggle",
    "Changing status saves immediately",
    "UI updates without page refresh",
    "Typecheck passes"
  ]
}
4

Filters and controls

Add a filter dropdown to a list
{
  "id": "US-004",
  "title": "Filter tasks by status",
  "acceptanceCriteria": [
    "Filter dropdown: All | Pending | In Progress | Done",
    "Filter persists in URL params",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ]
}

​
Stories That Are Too Big

These need to be split into multiple stories:
Problem: Too many components and dependenciesSplit into:
  1. Add dashboard schema/tables
  2. Create data aggregation queries
  3. Add dashboard page layout
  4. Add chart component for metrics
  5. Add filter controls
  6. Add export functionality
Problem: Spans database, middleware, UI, and session managementSplit into:
  1. Add users and sessions tables with migrations
  2. Add authentication middleware
  3. Create login page UI
  4. Add session handling and persistence
  5. Add logout functionality
  6. Add protected route guards
Problem: Touches too many endpoints and filesSplit into:
  1. Refactor user endpoints to new pattern
  2. Refactor task endpoints to new pattern
  3. Refactor notification endpoints to new pattern
  4. Update error handling across all endpoints
  5. Add validation middleware

​
Splitting Large Features

When you have a big feature, use this pattern:
1

Schema/Database First

Always start with database changes since later stories depend on them
US-001: Add notifications table to database
2

Backend Logic

Add server actions and business logic
US-002: Create notification service for sending notifications
3

Basic UI

Add the core UI components
US-003: Add notification bell icon to header
US-004: Create notification dropdown panel
4

Interactive Features

Add user interactions and state management
US-005: Add mark-as-read functionality
5

Settings/Configuration

Add preferences and configuration screens
US-006: Add notification preferences page
Each story should be independently verifiable and add value on its own. Avoid stories that are “half-finished” without the next story.

​
The Two-Sentence Test

Rule of thumb: If you cannot describe the change in 2-3 sentences, it’s too big. ✅ Good: “Add a status column to the tasks table with three possible values and a default of pending” ❌ Bad: “Build the entire task management system with status tracking, assignment, comments, and notifications”

​
Dependency Order Matters

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

​
Correct Order:

[
  {"priority": 1, "title": "Add status column to database"},
  {"priority": 2, "title": "Add status badge to UI"},
  {"priority": 3, "title": "Add status filter dropdown"}
]

​
Wrong Order:

[
  {"priority": 1, "title": "Add status filter dropdown"},  // Depends on schema!
  {"priority": 2, "title": "Add status column to database"}
]
The ralph skill automatically checks for proper dependency ordering when converting PRDs to prd.json. Use it to validate your story structure.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us