Ralph Loop Creator

Ralph Loop Creator

Core Purpose

Transform a rough idea, description, or PRD into a fully structured Ralph Loop prompt ready for execution. This automates the tedious work of structuring phases, validation criteria, and completion promises.

Based on @GeoffreyHuntley's Ralph Wiggum technique, @callam53's workflow guide.

Operating Philosophy

What This Skill IS

• Prompt scaffolder that creates structured Ralph-ready prompts
• Phase decomposer that breaks work into iterative chunks
• Validation designer that ensures each phase has clear success criteria
• Kanban translator that treats phases like tickets with ACs
• Quality gate that runs blind review before declaring ready

What This Skill IS NOT

• Interviewer (use /interview first if requirements are vague)
• Ralph runner (use /ralph-loop to actually run it)

When to Use This Skill

Use AFTER you have clarity on what to build:

Rough idea → /interview → /ralph-loop-creator → /ralph-loop
                  ↑              ↑
            (if spec has    (THIS SKILL)
             ambiguities)     │
                              ├── Generate PROMPT.md
                              ├── Blind Review (subagent)
                              ├── Fix issues if confidence < 7
                              └── Output ready-to-run command

Activation Protocol

When invoked with /ralph-loop-creator <input> [output-path]:

1. Parse input:

   • If file path: read the file (PRD, notes, rough plan)
   • If description: use the provided text

2. Assess completeness:

   • Are requirements clear enough to structure?
   • If not: suggest /interview first

3. Gather context:

   • Read relevant CLAUDE.md for project patterns
   • Check for existing architecture/infrastructure to reference
   • Identify dependencies and constraints

4. Generate PROMPT.md:

   • Mission statement + completion promise
   • Context section (what exists, architecture)
   • Scope (in/out)
   • Phases with tasks and validation
   • File structure
   • Environment variables
   • Decision log
   • Success metrics

5. Blind Review (critical step):

   • Spawn a subagent with ZERO context about the task
   • Have them review the PROMPT.md as if coming in cold
   • They report back:
     • What they expect to happen (validates clarity)
     • Implicit intent they're inferring (surfaces assumptions)
     • Pre-mortem: what could go wrong (finds gaps)
     • Confidence score 1-10 for autonomous execution
   • If confidence < 7: iterate on PROMPT.md to address issues
   • See "Blind Review Protocol" section below

6. Output:

   • Write to specified path (or suggest default)
   • Include confidence score from blind review
   • Provide the exact /ralph-loop command to run

PROMPT.md Template

Generate prompts following this structure:

# [Feature Name] - Ralph Loop Prompt

## Mission

[1-2 sentence description of what we're building]

**Completion Promise:** When all phases complete and [success criteria], output:

\`\`\`
<promise>[FEATURE_NAME] COMPLETE</promise>
\`\`\`

---

## Context

### What Already Exists

[Relevant existing infrastructure, patterns, files]

| Component | Location | Purpose        |
| --------- | -------- | -------------- |
| [Name]    | [Path]   | [What it does] |

### Architecture Overview

\`\`\`
[ASCII diagram if helpful]
\`\`\`

---

## Scope

### In Scope

- [ ] [Feature/requirement 1]
- [ ] [Feature/requirement 2]

### Out of Scope (Future)

- [Thing explicitly deferred]

---

## Phases

Work through these sequentially. Each phase should result in working, tested code.

### Phase 1: [Foundation/Setup]

**Goal:** [What this phase achieves]

**Tasks:**

1. [Specific task]
2. [Specific task]

**Validation:**

- [ ] [Testable criterion]
- [ ] [Testable criterion]

**Reference:** [Docs/links if relevant]

---

### Phase 2: [Core Feature]

[Same structure]

---

### Phase N: Testing & Documentation

**Goal:** Production-ready with tests and docs.

**Tasks:**

1. Unit tests for [components]
2. Integration tests for [flows]
3. Documentation at [location]

**Validation:**

- [ ] Tests passing
- [ ] Coverage > [X]%
- [ ] Docs complete

---

## Key Files to Create

\`\`\`
[File tree of expected output]
\`\`\`

---

## Environment Variables

\`\`\`bash
[Required env vars with descriptions]
\`\`\`

---

## Decision Log

| Decision | Choice   | Rationale |
| -------- | -------- | --------- |
| [What]   | [Choice] | [Why]     |

---

## Success Metrics

**Functional:**

- [Measurable criterion]

**Quality:**

- [Quality gate]

---

## Notes for Implementation

- [Important gotcha]
- [Pattern to follow]
- [Thing to avoid]

---

## When Complete

Output the completion promise:

\`\`\`
<promise>[FEATURE_NAME] COMPLETE</promise>
\`\`\`

Phase Design Principles

Good Phases

• Self-contained: Can be validated independently
• Incremental: Build on previous phases
• Testable: Clear pass/fail criteria
• Sized right: Not too big (overwhelming) or small (trivial)

Phase Sequencing

Typical flow:

1. Foundation - Setup, dependencies, scaffolding
2. Core - Main functionality (may be multiple phases)
3. Integration - Wire components together
4. Polish - Error handling, edge cases
5. Testing & Docs - Always last

Validation Criteria

Each phase needs checkboxes that are:

• Binary - Pass or fail, not subjective
• Testable - Can run a command or check to verify
• Specific - "Tests pass" not "code works"

Good:
- [ ] `npm test` passes with 0 failures
- [ ] Bot joins test meeting within 10 seconds
- [ ] Response latency < 2s measured in logs

Bad:
- [ ] Code is clean
- [ ] Feature works well
- [ ] Good performance

Iteration Estimation

Suggest max iterations based on complexity:

Output Format

After generating PROMPT.md and running blind review, provide:

## Ralph Loop Ready

Created: `[path/to/PROMPT.md]`

### Blind Review Results

**Confidence:** [X]/10
**Key findings:** [1-2 sentence summary of what reviewer caught]
**Changes made:** [What you fixed based on review, or "None needed"]

### To Run

\`\`\`
/ralph-loop [path/to/PROMPT.md] --max-iterations [N] --completion-promise "[PROMISE]"
\`\`\`

**Estimated phases:** [N]
**Suggested iterations:** [N]
**Completion promise:** [PROMISE]

Callam's Tips (Embedded)

Include these patterns in generated prompts:

1. Commit after each step - Add to phase tasks: "Commit changes with descriptive message"

2. Code review as phase - Include review validation:

   **Validation:**
   - [ ] Code review agent finds no critical issues
   

3. Kanban mindset - Treat each phase like a ticket with ACs

4. Brick by brick - Phases should be small enough to complete in 2-5 iterations each

5. Testing loop - Every phase should have runnable validation

Blind Review Protocol

Purpose: Pressure-test the PROMPT.md before autonomous execution. A fresh perspective catches ambiguities that the author is blind to.

How to Run the Blind Review

Spawn a subagent using the Task tool with this prompt template:

You are a senior technical reviewer specializing in PRDs and implementation plans
for autonomous AI execution. You have NO prior context about this project -
you're coming in completely blind.

Your task: Review the PRD at `[PATH_TO_PROMPT.md]` and provide a critical assessment.

## Review Instructions

1. **Read the PRD thoroughly** - understand what's being built
2. **Read relevant existing code** mentioned in the PRD to understand patterns
3. **Produce a review with these sections:**

### A. What I Expect to Happen
Describe concretely what an AI agent executing this plan would build.
Be specific about deliverables.

### B. Implicit Intent I'm Inferring
What is NOT explicitly stated but seems to be the underlying goal?
What assumptions is this plan making?

### C. Pre-Mortem: What Could Go Wrong
Imagine this ralph loop fails. Most likely causes:
- Ambiguous requirements that could be misinterpreted
- Missing context an AI agent would need
- Technical pitfalls or edge cases not addressed
- Validation criteria too vague or too strict
- Dependencies or blockers not mentioned

### D. Confidence Assessment
On a scale of 1-10, how confident are you that an AI agent could execute
this plan successfully without human intervention? Explain your rating.

### E. Recommended Changes (if any)
Specific, actionable changes to improve the PRD before execution.

Be brutally honest. Find problems BEFORE execution, not after.

Interpreting Results

Common Issues the Blind Review Catches

1. Underspecified types - "Create a dataclass" without field definitions
2. Undefined formulas - "Calculate P&L" without the actual formula
3. No test cases - Validation says "tests pass" but no expected inputs/outputs
4. Integration ambiguity - How new code relates to existing code unclear
5. Fragile references - Links to other branches, external docs that may not exist

When to Skip Blind Review

• Very simple prompts (2-3 phases, well-trodden patterns)
• User explicitly requests skipping
• Time-critical situations where speed > thoroughness

Default: Always run blind review for prompts with 4+ phases or novel implementations.

Integration with Your Workflow

This skill generates prompts compatible with your /ralph-loop plugin:

/ralph-loop-creator "Build a CLI tool that converts markdown to PDF"
→ Creates: ./docs/md-to-pdf/PROMPT.md
→ Runs blind review (confidence: 8/10)
→ Suggests: /ralph-loop "$(cat ./docs/md-to-pdf/PROMPT.md)" --max-iterations 30 --completion-promise "MD_TO_PDF_COMPLETE"

For complex features, use the full workflow:

/interview docs/X/prd.md              # Flesh out requirements
/ralph-loop-creator docs/X/prd.md     # Generate structured prompt + blind review
/ralph-loop ...                        # Execute