> ## 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

> Learn how to break down user stories to fit within a single Ralph iteration

# 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

<Warning>
  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.
</Warning>

## Right-Sized Stories

Each story should be describable in 2-3 sentences:

<Steps>
  <Step title="Database changes">
    Add a database column and migration

    ```json theme={null}
    {
      "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"
      ]
    }
    ```
  </Step>

  <Step title="UI components">
    Add a UI component to an existing page

    ```json theme={null}
    {
      "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"
      ]
    }
    ```
  </Step>

  <Step title="Backend logic">
    Update a server action with new logic

    ```json theme={null}
    {
      "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"
      ]
    }
    ```
  </Step>

  <Step title="Filters and controls">
    Add a filter dropdown to a list

    ```json theme={null}
    {
      "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"
      ]
    }
    ```
  </Step>
</Steps>

## Stories That Are Too Big

These need to be split into multiple stories:

<Accordion title="Build the entire dashboard">
  **Problem**: Too many components and dependencies

  **Split 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
</Accordion>

<Accordion title="Add authentication">
  **Problem**: Spans database, middleware, UI, and session management

  **Split 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
</Accordion>

<Accordion title="Refactor the API">
  **Problem**: Touches too many endpoints and files

  **Split 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
</Accordion>

## Splitting Large Features

When you have a big feature, use this pattern:

<Steps>
  <Step title="Schema/Database First">
    Always start with database changes since later stories depend on them

    ```
    US-001: Add notifications table to database
    ```
  </Step>

  <Step title="Backend Logic">
    Add server actions and business logic

    ```
    US-002: Create notification service for sending notifications
    ```
  </Step>

  <Step title="Basic UI">
    Add the core UI components

    ```
    US-003: Add notification bell icon to header
    US-004: Create notification dropdown panel
    ```
  </Step>

  <Step title="Interactive Features">
    Add user interactions and state management

    ```
    US-005: Add mark-as-read functionality
    ```
  </Step>

  <Step title="Settings/Configuration">
    Add preferences and configuration screens

    ```
    US-006: Add notification preferences page
    ```
  </Step>
</Steps>

<Tip>
  Each story should be independently verifiable and add value on its own. Avoid stories that are "half-finished" without the next story.
</Tip>

## 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:

```json theme={null}
[
  {"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:

```json theme={null}
[
  {"priority": 1, "title": "Add status filter dropdown"},  // Depends on schema!
  {"priority": 2, "title": "Add status column to database"}
]
```

<Note>
  The ralph skill automatically checks for proper dependency ordering when converting PRDs to `prd.json`. Use it to validate your story structure.
</Note>

## Next Steps

* [Customizing Prompts](/guides/customizing-prompts) - Tailor Ralph to your project
* [Browser Verification](/guides/browser-verification) - Verify UI changes work
* [Debugging](/guides/debugging) - Troubleshoot issues during execution