Ralph

---
description: Run task in iterative Ralph Wiggum Loop until verification passes
---

# /ralph

> "I'm helping!" - Ralph Wiggum

Run a task in an iterative loop until completion criteria are met. Named after the [Ralph Wiggum Loop](https://ghuntley.com/ralph/) pattern.

**This is an INTELLIGENT loop** - it leverages the entire Brief infrastructure:
- **Skills**: tdd, debugging, brief-patterns, security-patterns, testing-strategy
- **Commands**: TodoWrite, `brief ask --mode check`, Brief CLI
- **Methodology**: TDD (RED-GREEN-REFACTOR), systematic debugging
- **Guards**: Escalation at iteration 3, decision validation

## How It Works

1. **Skill Detection**: Analyzes task to load relevant skills (API, UI, security, etc.)
2. **First Iteration**: Agent receives task with full skill context and TDD instructions
3. **Verification**: Runs tests, lint, typecheck (configurable)
4. **Retry with Context**: If failed, agent gets debugging methodology + failure details
5. **Escalation**: At iteration 3, agent is warned to question the approach
6. **Success**: When verification passes, optionally runs full /prep

## Automatic Skill Detection

The loop analyzes your task and loads relevant skills:

| Task Contains | Skills Loaded |
|---------------|---------------|
| api, route, endpoint, database | brief-patterns, security-patterns |
| component, ui, page, button, form | brief-design, brief-patterns |
| bug, fix, error, broken | debugging |
| add, implement, create, new | tdd |
| test, coverage, spec | testing-strategy |
| extension, chrome | chrome-extension |
| mcp, tool | mcp-development |

**Always loaded**: tdd, debugging, brief-patterns, security-patterns, testing-strategy

## Usage

Run from terminal outside Claude Code:

```bash
# Basic usage
./.claude/scripts/ralph.sh "Implement the document search feature with tests"

# With Linear issue for context
./.claude/scripts/ralph.sh --linear BRI-123 "Fix the bug described in the issue"

# With full /prep on success
./.claude/scripts/ralph.sh --full-prep "Add pagination to the API"

Options:

• --max-iterations N - Maximum attempts (default: 10)
• --verify-only TYPE - tests, lint, typecheck, build, quick, all (default: all)
• --linear ID - Load Linear issue or project for context
• --brief TITLE - Load Brief document (PRD, spec, etc.) for context
• --budget USD - Max spend per iteration (default: 2.00)
• --full-prep - Run full /prep checklist on success
• --no-resume - Start fresh each iteration
• --verbose - Show full claude output
• --dry-run - Preview without executing

Core Philosophy

From the Ralph Wiggum methodology:

1. Iteration over perfection - Refinement matters more than first-attempt quality
2. Failures as data - Predictable failures reveal what guardrails to add
3. Operator skill determines success - Prompt quality matters more than model capability
4. Persistence wins - The loop handles retry logic automatically

Best Practices

Good Tasks for Ralph Loop

• Well-defined scope with clear acceptance criteria
• Automatic verification (tests, lint, type checks)
• Iterative refinement (bug fixes, feature implementation)
• Tasks that benefit from persistence

Not Ideal for Ralph Loop

• Exploratory research without clear completion criteria
• Tasks requiring human judgment for completion
• Highly interactive workflows needing constant feedback
• Open-ended creative tasks

Writing Effective Prompts

# Good: Clear task with verifiable outcome
./.claude/scripts/ralph.sh "Add input validation to POST /api/v1/documents.
Validation should reject empty titles and invalid folder IDs.
Add tests that verify the validation returns 400 errors."

# Bad: Vague task without clear completion
./.claude/scripts/ralph.sh "Make the API better"

Safety: Always Set Max Iterations

# Recommended
./.claude/scripts/ralph.sh --max-iterations 5 "Your task"

# Not recommended (uses default of 10)
./.claude/scripts/ralph.sh "Your task"

State Tracking

Each run creates state files in ~/.claude/ralph-state/:

• {run-id}.json - Iteration history, status, timestamps
• {run-id}.log - Full output log

View run history:

ls -la ~/.claude/ralph-state/
cat ~/.claude/ralph-state/*.json | jq .

Integration with Brief Infrastructure

The intelligent Ralph Loop uses the FULL Brief harness:

Skills Applied Per Iteration

Skill	First Iteration	Retry Iterations
tdd	RED-GREEN-REFACTOR instructions	Continue TDD cycle
debugging	Investigation methodology	4-phase debugging process
brief-patterns	API/DB/Component patterns	Pattern compliance check
security-patterns	HIPAA/SOC-2 requirements	Security validation
testing-strategy	80% coverage mandate	Coverage enforcement

Commands Used

Command/Tool	When Used
TodoWrite	Break task into trackable steps
brief ask --mode check	Before architectural decisions
Brief CLI	Product context when needed

Escalation Protocol

At iteration 3, the agent receives explicit instructions to:

1. STOP making random changes
2. Question the approach itself
3. Consider if the architecture is wrong
4. Potentially ask for help

Examples

Bug Fix with Linear Context

# Load issue context, apply debugging methodology
./.claude/scripts/ralph.sh --linear BRI-456 --verify-only tests \
  "Fix the foreign key constraint error described in the issue"

# The agent will:
# 1. Load BRI-456 from Linear for context
# 2. Apply debugging skill (4-phase investigation)
# 3. Write regression test FIRST (TDD)
# 4. Implement minimal fix
# 5. Loop until tests pass

Feature Implementation with Full Prep

# Implement with TDD, run full /prep on success
./.claude/scripts/ralph.sh --full-prep \
  "Add pagination to GET /api/v1/documents/search"

#