Ralph

Ralph Loop Skill

Create bulletproof development plans that execute reliably in YOLO mode.

Trigger Phrases

• "create a ralph loop for..."
• "ralph plan for..."
• "make a ralph loop and start with an interview"
• "yolo this feature..."

The Bulletproof Process

1. RESEARCH      - Understand the codebase
       ↓
2. INTERVIEW     - Gather requirements from user
       ↓
3. DESIGN        - Create architecture document
       ↓
4. EXPERT REVIEW - rp-cli plan mode review of design
       ↓
5. ORACLE        - (if complex) Deep architecture review
       ↓
6. CREATE PLAN   - Write atomic, complete tasks
       ↓
7. PLAN REVIEW   - rp-cli plan mode review of tasks
       ↓
8. FINALIZE      - User approval
       ↓
9. EXECUTE       - ralph yolo
       ↓
10. POST-REVIEW  - codex review of changes

Phase 1: RESEARCH (Required)

Before creating ANY interview, understand the codebase.

What to Research

1. Find existing patterns - How does similar functionality work?
2. Identify files to modify - What will change?
3. Understand the architecture - Where does this fit?
4. Note naming conventions - Match existing style

Research Commands

# Find relevant files
rg -l "keyword" --type swift
find . -name "*.swift" -path "*/Views/*" | head -20

# Understand existing patterns  
rg -A5 "struct.*View.*:" --type swift | head -50

# Check file structure
tree -L 3 path/to/relevant/code/

# Read key files
cat path/to/existing/similar/feature.swift | head -100

Research Output

Document findings:

## Research Findings

**Existing patterns:**
- Views are in Features/*/Views/
- State is in Features/*/State/
- Uses @Observable pattern

**Files that will change:**
- MainSplitView.swift (add new component)
- SomeState.swift (add new property)

**Files to create:**
- NewFeatureView.swift
- NewFeatureState.swift

**Naming conventions:**
- Views: SomethingView.swift
- State: SomethingState.swift

Phase 2: INTERVIEW (Required)

Use the interview tool to gather requirements. Never guess.

Interview Question Categories

Every interview MUST cover:

1. Scope - What exactly are we building?
2. Location - Where does it appear/integrate?
3. Behavior - How does it work?
4. Edge Cases - What could go wrong?
5. Acceptance - How do we know it's done?

Interview Template

{
  "title": "Ralph Plan: [Feature Name]",
  "description": "I've researched the codebase. Help me understand the requirements.\n\n**What I found:**\n[Brief research summary]",
  "questions": [
    {
      "id": "scope",
      "type": "single",
      "question": "What exactly should this feature do?",
      "options": ["Option A (describe)", "Option B (describe)", "Both", "Something else (explain below)"],
      "context": "Based on my research, [context]"
    },
    {
      "id": "scope_details",
      "type": "text",
      "question": "Any additional scope details?",
      "required": false
    },
    {
      "id": "location",
      "type": "single",
      "question": "Where should [feature] appear?",
      "options": ["Location A", "Location B", "New location"],
      "context": "Currently, similar features are in [location]"
    },
    {
      "id": "behavior_primary",
      "type": "single",
      "question": "When [trigger], what should happen?",
      "options": ["Behavior A", "Behavior B", "Configurable"]
    },
    {
      "id": "behavior_secondary",
      "type": "single",
      "question": "[Follow-up behavior question]?",
      "options": ["Option A", "Option B", "Option C"]
    },
    {
      "id": "edge_cases",
      "type": "multi",
      "question": "Which edge cases should I handle?",
      "options": ["Error state", "Empty state", "Loading state", "Offline mode", "Other (specify)"]
    },
    {
      "id": "edge_case_details",
      "type": "text",
      "question": "Any specific edge case handling?",
      "required": false
    },
    {
      "id": "acceptance",
      "type": "text",
      "question": "How will you verify this works correctly?",
      "context": "Describe what you'll test or look for"
    },
    {
      "id": "constraints",
      "type": "text",
      "question": "Any constraints or requirements I should know?",
      "required": false
    }
  ]
}

Phase 3: DESIGN (Required)

After interview, design the solution before writing tasks.

Design Document Template

## Design: [Feature Name]

### Interview Summary
- Scope: [answer]
- Location: [answer]  
- Behavior: [answer]
- Edge cases: [answer]
- Acceptance: [answer]

### Architecture

**New files to create:**
| File | Purpose |
|------|---------|
| NewView.swift | Main UI component |
| NewState.swift | State management |

**Files to modify:**
| File | Changes |
|------|---------|
| MainSplitView.swift | Add NewView to layout |
| AppState.swift | Add newState property |

**Integration points:**
- NewView will be added to MainSplitView in the detail area
- NewState will be owned by AppState
- NewView observes NewState via @Environment

### UI Mockup (if applicable)

┌─────────────────────────────────────┐ │ [Existing UI] │ ├─────────────────────────────────────┤ │ [New Feature Here] │ │ - Element A │ │ - Element B │ └─────────────────────────────────────┘

### Verification Checklist
- [ ] Feature appears in correct location
- [ ] Primary behavior works
- [ ] Edge cases handled
- [ ] User acceptance criteria met

Phase 4: EXPERT REVIEW (Required)

Use rp-cli plan mode to get expert review of the design.

Select Context Files

# Select files relevant to the design
rp-cli manage_selection '{
  "op": "set",
  "paths": [
    "path/to/existing/similar.swift",
    "path/to/where/integration/happens.swift"
  ]
}'

Request Design Review

rp-cli chat_send '{
  "mode": "plan",
  "new_chat": true,
  "chat_name": "Design Review: [Feature Name]",
  "message": "Please review this design for a new feature.\n\n## Design\n[paste design document]\n\n## Questions\n1. Is this architecture sound?\n2. Am I missing any integration points?\n3. Are there existing patterns I should follow?\n4. Any potential issues or edge cases?"
}'

Process Review Feedback

• Update design based on feedback
• Note any architectural changes
• If major issues found, return to Phase 3

Phase 5: ORACLE (Complex Features Only)

For complex features, get deep architecture review from Oracle (GPT-5 Pro).

When to Use Oracle

• Multiple subsystems involved
• New architectural patterns needed
• Cross-cutting concerns (auth, sync, caching)
• Integration with external services
• Performance-critical paths

Oracle Query Template

I need architecture advice for: [feature name]

## Context
[Brief project description]
[Current architecture]

## What I'm Building
[Feature description]
[Current design]

## Specific Questions
1. [Architecture question]
2. [Pattern question]
3. [Integration question]

## Constraints
[Performance, compatibility, etc.]

Process Oracle Response

• Update design with Oracle recommendations
• Document key decisions and rationale
• If significant changes, re-run Phase 4 review

Phase 6: CREATE PLAN (Critical)

Write tasks that are atomic, complete, and verifiable.

Task Anatomy

Every task MUST have:

1. WHAT - The specific change to make
2. WHERE - The exact file(s) to modify
3. HOW - Brief implementation approach (if not obvious)
4. VERIFY - How to confirm it worked

Task Sizing (Critical)

All tasks should be similar size - the LLM struggles with inconsistent sizing.

Why this matters: Large tasks get "swallowed up" - the LLM runs out of context window before finishing, producing incomplete or buggy code. If a task would take a human > 30 minutes, split it.

Task Writing Rules

Rule 1: Atomic = One Concern

❌ BAD: "Add sync panel with drag handle and animations" ✅ GOOD: Three separate tasks

Rule 2: Consistent Size

❌ BAD: Mix of tiny ("add import") and huge ("implement feature") tasks ✅ GOOD: All tasks take roughly 5-15 minutes of LLM work

Rule 3: Complete = Create + Integrate

❌ BAD: "Create SyncConsolePanel view" ✅ GOOD: "Create SyncConsolePanel view in SharedUI/Common/ AND replace SyncProgressView with it in MainSplitView.swift"

Rule 4: Specific Files Named

❌ BAD: "Add the button to the toolbar" ✅ GOOD: "Add refresh button to toolbar in MediaOrganizationView.swift toolbarContent"

Rule 5: Verification Included

❌ BAD: "Add drag handle" ✅ GOOD: "Add drag handle to panel. VERIFY: Dragging handle resizes panel height"

Plan Structure

# Plan: [Feature Name]

## Context
[What we're building and why]

## Interview Responses ([date])
- Scope: [answer]
- Location: [answer]
- Behavior: [answer]

## Design Review Notes
[Key feedback from rp-cli review]
[Oracle recommendations if applicable]

## Tasks

### Phase 1: Foundation
- [ ] 1.1 [Task with WHAT, WHERE, VERIFY]
- [ ] 1.2 [Task with WHAT, WHERE, VERIFY]

### Phase 2: Core Implementation  
- [ ] 2.1 [Task with WHAT, WHERE, VERIFY]
- [ ] 2.2 [Task with WHAT, WHERE, VERIFY]

### Phase 3: Integration
- [ ] 3.1 [Task with WHAT, WHERE, VERIFY]

### Phase 4: Verification
- [ ] 4.1 VERIFY: [Acceptance criteria 1]
- [ ] 4.2 VERIFY: [Acceptance criteria 2]

## Success Criteria
- [ ] [Criterion 1 from interview]
- [ ] [Criterion 2 from interview]

## Files Changed
| File | Action |
|------|--------|
| path/to/new.swift | CREATE |
| path/to/existing.swift | MODIFY |

Phase 7: PLAN REVIEW (Required)

Use rp-cli plan mode to review the task list before execution.

Select Plan Context

# Select files that will be modified
rp-cli manage_selection '{
  "op": "set", 
  "paths": [
    "path/to/file1.swift",
    "path/to/file2.swift"
  ]
}'

Request Plan Review

rp-cli chat_send '{
  "mode": "plan",
  "new_chat": true,
  "chat_name": "Plan Review: [Feature Name]",
  "message": "Please review this implementation plan.\n\n## Plan\n[paste full plan]\n\n## Review Checklist\n1. Does every CREATE task have a corresponding INTEGRATE task?\n2. Are all file paths correct and specific?\n3. Is each task atomic (one concern)?\n4. Does each task have a VERIFY step?\n5. Are there any missing tasks or integration points?\n6. Will this plan work in YOLO mode (non-interactive)?"
}'

Process Review Feedback

• Fix any issues identified
• Add missing tasks
• Clarify ambiguous descriptions
• Ensure all integration points covered

Phase 8: FINALIZE (Required)

Get user approval before execution.

Finalization Checklist

Before presenting to user, verify:

• Every "create" task has a corresponding "integrate" task
• Every task names specific files
• Every task has a VERIFY step
• Phase 4 has explicit verification tasks
• Success criteria match interview answers
• Files Changed table is complete
• Design review feedback incorporated
• Plan review feedback incorporated

Present to User

## Plan Ready: [Feature Name]

**Summary:**
- [N] tasks across [M] phases
- [X] files to create, [Y] files to modify

**Reviews completed:**
- ✅ Design review (rp-cli plan mode)
- ✅ Plan review (rp-cli plan mode)
- [✅ Oracle review (if applicable)]

**Key decisions:**
- [Decision 1 from interview/reviews]
- [Decision 2 from interview/reviews]

**How to proceed:**
1. **Review full plan** - See all tasks
2. **Edit plan** - Make changes before running
3. **Launch YOLO** - Execute all tasks automatically
4. **Interactive mode** - Work task by task

Ready to launch?

Phase 9: EXECUTE

Launch YOLO Mode

cd /path/to/project
ralph yolo
# Type 'yolo' to confirm
# Runs all tasks non-interactively
# Auto-commits each task
# Codex review runs automatically at end

Monitor Execution

• Watch for build failures
• Note any tasks that seem to struggle
• Be ready to intervene if needed

On Failure

ralph status    # See where we stopped
ralph next      # Fix the issue interactively
ralph yolo      # Continue from current task

Phase 10: POST-REVIEW (Required)

After YOLO completes, review the changes.

Automatic Codex Review

Ralph automatically runs codex review after YOLO completes:

Running final codex review on N commits (abc123..def456)...

If codex review doesn't run automatically:

codex review --base <start-commit>

Manual Verification

For UI changes, verify visually:

gj run ms  # Or appropriate run command
# Check that feature works as expected

rp-cli Post-Implementation Review (Optional)

For complex changes, request a post-implementation review:

rp-cli manage_selection '{
  "op": "set",
  "paths": ["files/that/changed.swift"]
}'

rp-cli chat_send '{
  "mode": "plan",
  "new_chat": true,
  "chat_name": "Post-Review: [Feature Name]",
  "message": "Please review these changes for:\n1. Code quality issues\n2. Missing error handling\n3. Performance concerns\n4. Consistency with project patterns"
}'

Anti-Patterns (DO NOT DO)

rp-cli Quick Reference

Setup Selection

rp-cli manage_selection '{"op": "set", "paths": ["file1.swift", "file2.swift"]}'
rp-cli manage_selection '{"op": "get", "view": "files"}'

Plan Mode Review

rp-cli chat_send '{
  "mode": "plan",
  "new_chat": true,
  "chat_name": "Review: Topic",
  "message": "Review request..."
}'

Continue Conversation

rp-cli chat_send '{
  "mode": "plan",
  "new_chat": false,
  "message": "Follow-up question..."
}'

List Available Models

rp-cli list_models

Example: Complete Flow

User: "Create a ralph loop for Xcode-style bottom console panel"

1. Research

rg -l "SyncProgress" --type swift
# Found: SyncProgressView.swift (current implementation)
# Found: MainSplitView.swift (where it's used)

cat "SharedUI/Common/SyncProgressView.swift" | head -50
# Current: floating card overlay

cat "Features/MediaOrganization/Views/MainSplitView.swift" | grep -A10 "SyncProgress"
# Integration point identified

2. Interview

{
  "title": "Ralph Plan: Xcode-style Console Panel",
  "description": "Currently using floating card. You want Xcode-style bottom panel.",
  "questions": [
    {"id": "style", "question": "Confirm: Bottom slide-up panel like Xcode console?"},
    {"id": "resize", "question": "Should panel be resizable via drag?"},
    {"id": "collapse", "question": "Should panel collapse to header-only?"},
    {"id": "shortcut", "question": "Keyboard shortcut? (suggest ⌘⇧C)"},
    {"id": "acceptance", "question": "How will you verify it works?"}
  ]
}

3. Design

## Design: Xcode-style Console Panel

### Architecture
- CREATE: SyncConsolePanel.swift (new component)
- MODIFY: MainSplitView.swift (replace SyncProgressView)
- MODIFY: AppState.swift (add showSyncConsole toggle)

### Integration
- SyncConsolePanel replaces SyncProgressView in StatusFooter
- Same callbacks (onCancel, onPause, etc.)
- AppState.showSyncConsole controls visibility

4. Expert Review (rp-cli)

rp-cli manage_selection '{"op":"set","paths":["SharedUI/Common/SyncProgressView.swift","Features/MediaOrganization/Views/MainSplitView.swift"]}'

rp-cli chat_send '{"mode":"plan","new_chat":true,"chat_name":"Design Review: Console Panel","message":"Review this design..."}'

5. Create Plan

## Tasks

### Phase 1: Create Component
- [ ] 1.1 Create SyncConsolePanel.swift in SharedUI/Common/
      VERIFY: File compiles, preview renders

### Phase 2: Integration  
- [ ] 2.1 Replace SyncProgressView with SyncConsolePanel in MainSplitView.swift StatusFooter
      VERIFY: New panel appears at bottom when sync starts

### Phase 3: Features
- [ ] 3.1 Add drag handle for resizing
      VERIFY: Dragging changes panel height
- [ ] 3.2 Add collapse/expand toggle
      VERIFY: Panel collapses to header only

### Phase 4: Verification
- [ ] 4.1 VERIFY: Panel slides up from bottom (not floating)
- [ ] 4.2 VERIFY: ⌘⇧C toggles visibility
- [ ] 4.3 VERIFY: Drag handle resizes panel

6. Plan Review (rp-cli)

rp-cli chat_send '{"mode":"plan","new_chat":true,"message":"Review this plan for YOLO execution..."}'

7. Finalize & Execute

ralph yolo
# All tasks execute
# Codex review runs automatically

8. Post-Review

# Verify visually
gj run ms
# Check panel appears at bottom, drag works, etc.

Key Principles

1. Research first - Understand before asking
2. Interview always - Never assume requirements
3. Design before tasks - Architecture drives implementation
4. Review twice - Design review + Plan review via rp-cli
5. Atomic + Complete - One thing, fully integrated
6. Verify everything - Build passing ≠ feature working
7. Post-review always - Codex + manual verification