ralph-prompt-builder

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 |

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

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

1. How many distinct deliverables?

- One deliverable → Single Task

- 2-5 related deliverables → Multi-Task

- Complete application/tool → Project

- Analysis document → Research

1. Does it involve investigation before action?

- Yes, research required → Research

- No, implementation focus → Single/Multi/Project

1. What's the completion criteria?

- Tests pass → Single Task

- Multiple features working → Multi-Task

- Complete app running → Project

- Document produced → Research

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"

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

```bash

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

```

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

1. Per-phase tasks and deliverables
2. Final verification
3. 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

1. Deliverables at each phase
2. Evidence-based conclusions

Best practices:

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

Recommended iterations: 30-100

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

```

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

After generating a prompt:

```bash

# 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

```

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

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