Task Priority System

Complete example showing how to build a task priority feature from PRD to execution with Ralph

Task Priority System

This example demonstrates a complete Ralph workflow: from PRD to prd.json to autonomous execution. We’ll build a task priority system that lets users mark tasks as high, medium, or low priority.

The Feature

Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering capabilities.

1. Create the PRD

   First, use the PRD skill to generate a requirements document:

   Load the prd skill and create a PRD for task priority system
   

   The skill will ask clarifying questions:

   1. What is the primary goal of this feature?
      A. Help users focus on important tasks
      B. Improve task organization
      C. Enable team prioritization
      D. Other: [please specify]
   
   2. What priority levels do you need?
      A. Simple (High/Low)
      B. Standard (High/Medium/Low)
      C. Complex (P0/P1/P2/P3)
      D. Custom
   
   3. Where should priority be visible?
      A. Task list only
      B. Task list and detail view
      C. Everywhere tasks appear
      D. Only on hover
   

   Answer: 1A, 2B, 3C

   The skill saves the PRD to tasks/prd-task-priority.md.

2. Convert to prd.json

   Use the Ralph skill to convert the markdown PRD to JSON:

   Load the ralph skill and convert tasks/prd-task-priority.md to prd.json
   

   This generates prd.json with properly structured user stories:

   prd.json

   {
     "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": ""
       }
     ]
   }
   
3. Run Ralph

   Start the autonomous execution loop:

   ./scripts/ralph/ralph.sh 10
   

   Ralph will:

   1. Create branch ralph/task-priority
   2. Pick the first story (US-001)
   3. Implement the database migration
   4. Run typecheck
   5. Commit if checks pass
   6. Mark US-001 as passes: true
   7. Move to US-002
   8. Continue until all stories pass
4. Monitor Progress

   Check status at any time:

   # See which stories are done
   cat prd.json | jq '.userStories[] | {id, title, passes}'
   
   # View learnings from iterations
   cat progress.txt
   
   # Check commits
   git log --oneline -10
   

Execution Timeline

Iteration 1: Database Schema

Story: US-001 - Add priority field to database

Ralph spawns an Amp instance that:

• Reads the existing schema
• Adds priority column with enum type
• Generates migration file
• Runs migration
• Runs typecheck

Commit: feat: add priority field to tasks table

Updates to progress.txt:

US-001: PASS
- Added priority column to tasks table
- Used enum type: 'high' | 'medium' | 'low'
- Default value: 'medium'
- Migration ran successfully

Iteration 2: Priority Badges

Story: US-002 - Display priority indicator on task cards

Ralph spawns a fresh Amp instance that:

• Reads git history and progress.txt for context
• Finds the task card component
• Adds Badge component with color variants
• Verifies in browser using dev-browser skill
• Runs typecheck

Commit: feat: add priority badges to task cards

Updates to progress.txt:

US-002: PASS
- Added priority badge to TaskCard component
- Colors: red (high), yellow (medium), gray (low)
- Used existing Badge component with color prop
- Verified visually in browser

Iteration 3: Edit UI

Story: US-003 - Add priority selector to task edit

Ralph spawns a fresh Amp instance that:

• Finds the task edit modal
• Adds Select component for priority
• Wires up to server action
• Verifies in browser using dev-browser skill
• Runs typecheck

Commit: feat: add priority selector to task edit modal

Iteration 4: Filtering

Story: US-004 - Filter tasks by priority

Ralph spawns a fresh Amp instance that:

• Adds filter dropdown to task list header
• Implements URL param persistence
• Filters query based on selected priority
• Adds empty state message
• Verifies in browser using dev-browser skill
• Runs typecheck

Commit: feat: add priority filter to task list

Final output:

✅ All stories complete
<promise>COMPLETE</promise>

Key Lessons

Story Sizing

Each story was completable in one context window:

Good sizing:

• US-001: Just database schema + migration
• US-002: Just display logic in one component
• US-003: Just edit UI in one modal
• US-004: Just filtering logic

Would be too big:

• “Build entire priority system” (split into 4 stories)
• “Add priority with notifications” (separate concerns)

Story Order

Dependencies were ordered correctly:

1. Schema first (US-001) - Nothing works without data model
2. Display next (US-002) - Show existing data
3. Edit after (US-003) - Modify the data
4. Filter last (US-004) - Uses all previous work

Wrong order would fail:

• UI before schema = type errors
• Filter before display = nothing to filter

Acceptance Criteria

Every criterion was verifiable:

Good (specific):

• “Add priority column: ‘high’ | ‘medium’ | ‘low’”
• “Badge colors: red=high, yellow=medium, gray=low”
• “Filter dropdown with options: All | High | Medium | Low”

Bad (vague):

• “Works correctly”
• “Good UX”
• “Handles edge cases”

Each story ended with:

• “Typecheck passes” (always)
• “Verify in browser using dev-browser skill” (UI stories)

Memory Between Iterations

Each iteration is a fresh context. Memory comes from:

• Git history: Previous commits show what’s done
• progress.txt: Learnings and context from each story
• prd.json: Which stories have passes: true

Without these, each iteration would start from scratch.

Try It Yourself

Use this example as a template:

1. Copy prd.json.example to your project as prd.json
2. Run ./scripts/ralph/ralph.sh 10
3. Watch Ralph complete all four stories
4. Review commits and progress.txt to understand the flow

This example is based on the actual prd.json.example file included with Ralph. It demonstrates real patterns used in production.