adaptationio/ralph-prompt-builder

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:

1. Classify your task
2. Route to the appropriate generator
3. Guide you through required inputs
4. 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:

1. 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

2. How many distinct deliverables?

   • One deliverable → Single Task
   • 2-5 related deliverables → Multi-Task
   • Complete application/tool → Project
   • Analysis document → Research

3. Does it involve investigation before action?

   • Yes, research required → Research
   • No, implementation focus → Single/Multi/Project

4. 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:

1. Verify requirements are complete
2. Check verification commands are correct
3. Confirm completion criteria match your needs
4. 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:

1. Task title and objective
2. Context
3. Requirements
4. Success criteria (checkboxes)
5. Verification steps with commands
6. TDD approach
7. Completion conditions
8. 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:

1. Task inventory table
2. Phase breakdown (Foundation → Core → Enhancement → Validation)
3. Per-phase tasks with deliverables
4. Phase checkpoints
5. Progress tracking
6. 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:

1. Project vision and specs
2. Six phases:
   • Phase 0: Setup
   • Phase 1: Architecture
   • Phase 2: Core
   • Phase 3: Features
   • Phase 4: Testing
   • Phase 5: Documentation
3. Per-phase tasks and deliverables
4. Final verification
5. 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:

1. Research objective and scope
2. Five phases:
   • Phase 1: Discovery
   • Phase 2: Analysis
   • Phase 3: Synthesis
   • Phase 4: Recommendations
   • Phase 5: Documentation
3. Deliverables at each phase
4. 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:

1. Scope too large → Split into smaller tasks
2. Unclear criteria → Make success criteria more specific
3. External dependencies → Document or mock dependencies
4. 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