Ralph Prompt Builder (Master Orchestrator)

Overview

Master skill for generating prompts optimized for the Ralph Wiggum autonomous loop technique. This orchestrator analyzes your task description and routes to the appropriate specialized generator:

Task Type	Generator	Best For
Single focused task	`ralph-prompt-single-task`	Bug fixes, single features, refactoring
Multiple related tasks	`ralph-prompt-multi-task`	CRUD, multi-step features, migrations
Complete project	`ralph-prompt-project`	Greenfield apps, libraries, tools
Research/Analysis	`ralph-prompt-research`	Audits, planning, investigations

Quick Start

Generate any Ralph prompt:

Use ralph-prompt-builder to create a prompt for: [describe your task]

Example:

Use ralph-prompt-builder to create a prompt for: Implementing user authentication with JWT for our Express API

The skill will:

Classify your task
Route to the appropriate generator
Guide you through required inputs
Output a ready-to-use Ralph prompt

Task Classification

How Tasks Are Classified

Indicators	Classification	Generator
Fix, repair, single change, one module	Single Task	`ralph-prompt-single-task`
Multiple features, CRUD, several endpoints	Multi-Task	`ralph-prompt-multi-task`
Build from scratch, new app, create tool	Project	`ralph-prompt-project`
Analyze, audit, compare, plan, investigate	Research	`ralph-prompt-research`

Classification Questions

To classify your task, consider:

Is this creating something new from scratch or modifying existing code?
- New from scratch → Project or Multi-Task
- Modifying existing → Single Task or Multi-Task
How many distinct deliverables?
- One deliverable → Single Task
- 2-5 related deliverables → Multi-Task
- Complete application/tool → Project
- Analysis document → Research
Does it involve investigation before action?
- Yes, research required → Research
- No, implementation focus → Single/Multi/Project
What's the completion criteria?
- Tests pass → Single Task
- Multiple features working → Multi-Task
- Complete app running → Project
- Document produced → Research

Classification Examples

Single Task Examples

"Fix the race condition in token refresh"
"Add pagination to the users endpoint"
"Refactor database queries to use async/await"
"Write tests for the auth module"
"Optimize the image upload function"

Multi-Task Examples

"Implement CRUD for Products resource"
"Add login, signup, logout, and password reset"
"Set up CI/CD pipeline with lint, test, build, deploy"
"Add validation, error handling, and logging to API"
"Create user, profile, and settings endpoints"

Project Examples

"Build a REST API for a todo list application"
"Create a CLI tool for database migrations"
"Build a URL shortener service"
"Create a markdown documentation generator"
"Build an authentication microservice"

Research Examples

"Analyze the codebase for security vulnerabilities"
"Compare React vs Vue vs Svelte for our needs"
"Create a migration plan from MongoDB to PostgreSQL"
"Audit dependencies for outdated packages"
"Document the current API architecture"

Workflow

Step 1: Describe Your Task

Provide a description including:

What needs to be done
What technology/context
Any specific requirements
Desired outcome

Template:

Task: [What you want to accomplish]
Context: [Relevant background - tech stack, existing code, etc.]
Requirements: [Specific requirements or constraints]
Outcome: [What success looks like]

Step 2: Review Classification

The orchestrator will classify your task and explain why:

CLASSIFICATION: [Task Type]
REASONING: [Why this classification]
GENERATOR: ralph-prompt-[type]

Does this classification look correct? If not, specify your preferred type.

Step 3: Provide Generator Inputs

Each generator requires specific inputs:

Single Task:

Task description
Success criteria (how to verify)
Completion promise text

Multi-Task:

List of tasks
Dependencies between tasks
Final completion promise

Project:

Project description
Tech stack
Feature list
Completion promise

Research:

Research objective
Scope (in/out)
Deliverable format
Completion promise

Step 4: Generate & Review

The appropriate generator creates the prompt. Review and customize:

Verify requirements are complete
Check verification commands are correct
Confirm completion criteria match your needs
Adjust max-iterations recommendation

Step 5: Execute with Ralph

/ralph-wiggum:ralph-loop "[generated prompt]" --completion-promise "[YOUR_PROMISE]" --max-iterations [recommended]

Generator Summaries

ralph-prompt-single-task

Purpose: Focused tasks with clear success criteria

Structure:

Task title and objective
Context
Requirements
Success criteria (checkboxes)
Verification steps with commands
TDD approach
Completion conditions
If stuck guidance

Best practices:

Include actual test commands
Make criteria binary (pass/fail)
Include TDD loop

Recommended iterations: 15-35

ralph-prompt-multi-task

Purpose: Multiple related tasks organized in phases

Structure:

Task inventory table
Phase breakdown (Foundation → Core → Enhancement → Validation)
Per-phase tasks with deliverables
Phase checkpoints
Progress tracking
Final verification

Best practices:

Group tasks into logical phases
Clear dependencies
Document checkpoints

Recommended iterations: 35-100

ralph-prompt-project

Purpose: Complete projects from scratch

Structure:

Project vision and specs
Six phases:
- Phase 0: Setup
- Phase 1: Architecture
- Phase 2: Core
- Phase 3: Features
- Phase 4: Testing
- Phase 5: Documentation
Per-phase tasks and deliverables
Final verification
Progress tracking

Best practices:

Define non-goals explicitly
Complete all phases in order
Don't skip testing/documentation

Recommended iterations: 60-200

ralph-prompt-research

Purpose: Analysis, audits, planning, investigations

Structure:

Research objective and scope
Five phases:
- Phase 1: Discovery
- Phase 2: Analysis
- Phase 3: Synthesis
- Phase 4: Recommendations
- Phase 5: Documentation
Deliverables at each phase
Evidence-based conclusions

Best practices:

Define scope boundaries clearly
Create artifacts as you go
Support conclusions with evidence

Recommended iterations: 30-100

Common Patterns

Choosing a Completion Promise

Good promises are:

Specific to the task
Verifiable (you can check if it's true)
Action-oriented

Examples:

Task Type	Good Promise	Why
Bug fix	`AUTH_FIX_COMPLETE`	Specific to what was fixed
CRUD	`PRODUCT_CRUD_DONE`	Names the resource
Project	`TODO_API_V1_COMPLETE`	Identifies the project
Research	`SECURITY_AUDIT_DELIVERED`	References deliverable

The Ralph Philosophy

The Ralph Wiggum technique is built on a key insight: failures are deterministic and fixable.

Deterministically bad: When prompts fail, they fail in predictable ways
Fixable through iteration: Each failure provides data to improve
Prompt tuning > tool changing: Fix failures by improving the prompt, not switching approaches

This means: Don't fear failures. They're expected and correctable. The loop will iterate until success.

Setting Max Iterations

Base recommendations by complexity:

Complexity	Single Task	Multi-Task	Project	Research
Simple	15	35	60	30
Medium	25	50	100	50
Complex	35	70	150	80
Very Complex	-	100	200	100

Adjust based on:

Familiarity with codebase (-20%)
External dependencies (+30%)
Unclear requirements (+50%)
Comprehensive testing needed (+25%)

Splitting Large Tasks

If task feels too large, consider splitting:

Project → Multiple Projects:

Instead of: "Build complete e-commerce platform"
Split into:
1. Project: User authentication service
2. Project: Product catalog API
3. Project: Shopping cart service
4. Project: Order processing service

Multi-Task → Separate Multi-Tasks:

Instead of: "Build full admin dashboard"
Split into:
1. Multi-Task: User management (CRUD + roles)
2. Multi-Task: Analytics dashboard
3. Multi-Task: Settings panel

Troubleshooting

Task Won't Complete

Symptoms: Hitting max iterations without completion

Causes and fixes:

Scope too large → Split into smaller tasks
Unclear criteria → Make success criteria more specific
External dependencies → Document or mock dependencies
Infinite tests → Check for flaky tests

Wrong Generator Selected

Fix: Specify the generator explicitly:

Use ralph-prompt-single-task (not multi-task) for: [task]

Prompt Too Vague

Fix: Ensure your input includes:

Specific files/modules affected
Actual test commands
Concrete success criteria
Technology context

Integration with Ralph Loop

After generating a prompt:

# Copy the generated prompt to a file or use directly
/ralph-wiggum:ralph-loop "[YOUR_GENERATED_PROMPT]" \
  --completion-promise "YOUR_PROMISE" \
  --max-iterations 50

# Monitor progress
head -10 .claude/ralph-loop.local.md

# Cancel if needed
/ralph-wiggum:cancel-ralph

Best Practices

DO:

Start with the right generator for your task type
Provide complete context and requirements
Include specific verification commands
Set appropriate max-iterations for complexity
Review generated prompts before running

DON'T:

Use vague task descriptions
Skip the classification step
Ignore the "If Stuck" guidance in generated prompts
Set max-iterations too low (iterations are normal)
Expect first-try perfection—Ralph embraces iteration

Quick Reference

Task Type Decision Tree

Is this research/analysis/planning?
├─ YES → ralph-prompt-research
└─ NO → Is this building a complete app from scratch?
         ├─ YES → ralph-prompt-project
         └─ NO → Are there multiple related deliverables?
                  ├─ YES → ralph-prompt-multi-task
                  └─ NO → ralph-prompt-single-task

Input Checklist

Before generating, have ready:

Clear task description
Technology context (language, framework)
Success criteria (how to verify done)
Completion promise text
Any specific requirements

Output Checklist

Before running the prompt:

All requirements captured
Verification commands are correct
Success criteria are binary (pass/fail)
TDD/iteration approach included
"If Stuck" guidance provided
Max iterations set appropriately

Specialized Generators:

ralph-prompt-single-task - Single focused implementations
ralph-prompt-multi-task - Multiple related tasks
ralph-prompt-project - Complete projects
ralph-prompt-research - Analysis and planning

Ralph Loop Commands:

/ralph-wiggum:ralph-loop - Start a loop
/ralph-wiggum:cancel-ralph - Cancel active loop
/ralph-wiggum:help - Get help