Ralphing

Type Rules

• setup — Project scaffolding, installing dependencies, configuring tools. Description is free-form.
• miscellaneous — Cleanup, refactoring, non-feature work. Description is free-form.
• user_story — Feature work driven by user value. Description must use: "As a [user], I want [feature] so that [benefit]"

IDs

All tasks share a single sequential counter: T-1, T-2, T-3, ... regardless of type.

Write to: prd.json

Branch Name

• Use prefix feat/ followed by a slug derived from the PRD title
• Slug: lowercase, hyphens, 3-6 words
• Example: feat/task-priority-system

Task Size: The Number One Rule

Each task must be completable in ONE ralphing iteration (one context window).

Each iteration spawns a fresh AI instance with clean context. If a task is too big, the agent runs out of context before finishing and produces broken code.

Right-sized tasks:

• 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
• Install and configure a package

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 task per endpoint or pattern

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.

Task Ordering: Dependencies First

Tasks execute in priority order. Earlier tasks must not depend on later ones. Order purely by dependency — task type does not determine position.

Correct order:

1. Anything a later task depends on (e.g. install a package before using it)
2. Schema / database changes (migrations)
3. Server actions / backend logic
4. UI components that use the backend
5. Dashboard / summary views that aggregate data

Acceptance Criteria: Must Be Verifiable

Each criterion must be something the agent can CHECK, not something vague.

Good (verifiable):

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Clicking delete shows confirmation dialog"
• "Typecheck passes"

Bad (vague):

• "Works correctly"
• "User can do X easily"
• "Handles edge cases"

Always include as final criterion for user_story tasks:

"Typecheck passes"

For user_story tasks with testable logic, also include:

"Tests pass"

For user_story tasks that change UI, also include:

"Verify in browser using dev-browser skill"

setup and miscellaneous tasks do not require automatic criteria — use only what is verifiable for that task.

Conversion Rules

1. Each item (setup step, story, cleanup, etc.) becomes one task entry
2. IDs: Single sequential counter — T-1, T-2, T-3, ... regardless of type
3. Priority: Based on dependency order, then document order
4. All tasks: passes: false and empty notes
5. branchName: Derive from feature name, kebab-case, prefixed with feat/
6. user_story tasks: always add "Typecheck passes" as final acceptance criterion
7. setup / miscellaneous tasks: only include criteria that are actually verifiable

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add user notification system"

Split into:

1. T-1: Add notifications table to database
2. T-2: Create notification service for sending notifications
3. T-3: Add notification bell icon to header
4. T-4: Create notification dropdown panel
5. T-5: Add mark-as-read functionality
6. T-6: Add notification preferences page

Each is one focused change that can be completed and verified independently.

Example

Input PRD:

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

Output prd.json:

{
  "project": "TaskApp",
  "branchName": "feat/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "tasks": [
    {
      "id": "T-1",
      "type": "setup",
      "title": "Install required packages",
      "description": "Install any packages needed for the status feature.",
      "acceptanceCriteria": [
        "Dependencies installed and lockfile updated"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "T-2",
      "type": "user_story",
      "title": "Add status field to tasks table",
      "description": "As a developer, I want to store task status in the database so that status persists across sessions.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "T-3",
      "type": "user_story",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance so that I know which tasks are in progress.",
      "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"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "T-4",
      "type": "user_story",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list so that I don't have to open each task.",
      "acceptanceCriteria": [
        "Each row has status dropdown or toggle",
        "Changing status saves immediately",
        "UI updates without page refresh",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    },
    {
      "id": "T-5",
      "type": "user_story",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses so that I can focus on relevant tasks.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 5,
      "passes": false,
      "notes": ""
    }
  ]
}

Checklist Before Writing

• Each task is completable in one iteration (small enough)
• Tasks are ordered by dependency (nothing depends on a later task)
• Every user_story task has "Typecheck passes" as final criterion
• UI user_story tasks have "Verify in browser using dev-browser skill"
• user_story descriptions use the "As a [user]..." format
• Acceptance criteria are verifiable, not vague
• All tasks start with passes: false