Ralph Workflow Skill

This skill provides the autonomous backlog processing workflow used by Ralph, following the Universal Quality Workflow for consistent code quality.

When to Use This Skill

Processing multiple tickets autonomously
Working through a product backlog
Implementing features from a PRD file
Running in background agent mode

Universal Quality Workflow

Brain Dump enforces this status flow for all tickets:

backlog → ready → in_progress → ai_review → human_review → done

in_progress: Active development (code being written)
ai_review: Automated quality review by code review agents
human_review: Demo approval by human reviewer
done: Complete and approved

The Ralph Workflow

1. Read Context Files

plans/prd.json     - Product requirements (auto-generated from tickets)
plans/progress.txt - Notes from previous iterations

2. Start Ticket Work

Use the MCP tool to create branch and set up tracking:

workflow "start-work"({ ticketId: "story-id" });

This automatically:

Creates a git branch: feature/{ticket-id}-{slug}
Sets ticket status to in_progress
Posts a "Starting work" comment

3. Pick ONE Task

From prd.json, find a user story where passes: false:

Prioritize by priority field (high > medium > low)
Only work on ONE task per iteration

4. Create Session for Tracking

session "create"({ ticketId: "story-id" });
session "update-state"({ sessionId: "...", state: "analyzing" });

5. Implement Feature

session "update-state"({ sessionId: "...", state: "implementing" });

Write the code
Discover validation commands from this project's docs/config
Run the project's own validation commands
Verify acceptance criteria

6. Commit Changes

session "update-state"({ sessionId: "...", state: "committing" });

git add -A
git commit -m "feat(<ticket-id>): <description>"

7. Complete Implementation (Move to AI Review)

IMPORTANT: Do NOT directly set status to "done". Use workflow "complete-work":

workflow "complete-work"({
  ticketId: "story-id",
  summary: "Implemented login form with validation and API integration",
});

This:

Validates that a current test_report comment exists with exact pass/fail/skipped results
Moves ticket to ai_review status
Posts work summary as comment
Updates PRD file (passes: true)

8. Run AI Review Agents

After workflow "complete-work", run the review pipeline:

// Submit findings from each agent
review "submit-finding"({
  ticketId: "story-id",
  agent: "code-reviewer",
  severity: "major",
  category: "type-safety",
  description: "Missing null check on user input",
});

Review agents to run:

code-reviewer - Code quality and style
silent-failure-hunter - Error handling issues
code-simplifier - Code simplification opportunities

9. Fix Critical/Major Findings

If any critical or major findings:

// Fix the issue, then mark as fixed
review "mark-fixed"({
  findingId: "finding-id",
  fixStatus: "fixed",
  fixDescription: "Added null check before accessing property",
});

10. Check Review Complete

review "check-complete"({ ticketId: "story-id" });
// Returns { complete: true/false, openCritical: 0, openMajor: 0, ... }

11. Generate Demo Script (Move to Human Review)

Once all critical/major findings are fixed:

review "generate-demo"({
  ticketId: "story-id",
  steps: [
    {
      order: 1,
      description: "Navigate to login page",
      expectedOutcome: "Login form displays",
      type: "manual",
    },
    {
      order: 2,
      description: "Enter valid credentials",
      expectedOutcome: "User is logged in",
      type: "manual",
    },
  ],
});

This moves ticket to human_review status.

12. STOP - Wait for Human Approval

The workflow stops here. A human must:

Review the demo script
Run through the steps
Provide approval via review "submit-feedback"

If approved → ticket moves to done If rejected → stays in human_review with feedback

13. Update Progress File

Append to plans/progress.txt:

## Iteration N - [timestamp]
- Completed: <ticket title>
- Changes: <brief summary>
- Review: <number of findings, all fixed>
- Notes: <any learnings or issues>

14. Check Completion

If ALL stories have passes: true and are in done status:

Push branch: git push -u origin <branch-name>
Create PR using gh pr create
Output: PRD_COMPLETE

Otherwise, the next iteration picks the next task.

PRD File Format

{
  "projectName": "My Project",
  "projectPath": "/path/to/project",
  "epicTitle": "Feature Name",
  "userStories": [
    {
      "id": "ticket-id",
      "title": "Task title",
      "description": "What to build",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "priority": "high",
      "tags": ["frontend"],
      "passes": false
    }
  ],
  "generatedAt": "2024-01-01T00:00:00.000Z"
}

Progress File Format

# Ralph Progress Log

# Use this to leave notes for the next iteration

## Iteration 1 - 2024-01-01 10:00

- Completed: Add login form
- Changes: Created LoginForm.tsx, added validation
- Review: 2 findings (1 major, 1 minor) - all fixed
- Notes: Auth API returns different error format than expected

## Iteration 2 - 2024-01-01 10:30

- Completed: Add auth API integration
- Changes: Updated auth.ts, added error handling
- Review: 1 finding (suggestion) - applied
- Notes: All tests passing

Important Rules

One task per iteration - Keeps context focused
Always validate - Run project-specific validation before completing
Use workflow "complete-work" - Never directly set status to "done"
Run all review agents - Fix critical/major before demo
Stop at human_review - Wait for human approval
Document issues - Add blockers to progress.txt
Never commit to main/dev - Always use feature branches

ralph-workflow