Ralph Loop: Iterative Development Methodology

Configure and run self-correcting iterative development loops for autonomous AI coding. Ralph loops iterate until completion criteria are met, with proper state management and handoff support.

Triggers

Use this skill when:

• Running autonomous coding sessions
• Implementing self-correcting workflows
• Building iterative development pipelines
• Creating loops that validate and fix their own work
• Setting up background coding tasks
• Keywords: ralph, iterative, loop, autonomous, self-correcting, iteration, background, continuous

Concept Overview

RALPH LOOP CYCLE

  ┌─────────────────────────────────────────────┐
  │                                             │
  │    ┌──────────┐                             │
  │    │  Start   │                             │
  │    │ Iteration│                             │
  │    └────┬─────┘                             │
  │         │                                   │
  │         v                                   │
  │    ┌──────────┐     ┌──────────┐           │
  │    │   Work   │────>│ Validate │           │
  │    │          │     │          │           │
  │    └──────────┘     └────┬─────┘           │
  │                          │                  │
  │              ┌───────────┴───────────┐     │
  │              │                       │     │
  │              v                       v     │
  │         [FAIL]                  [PASS]     │
  │              │                       │     │
  │              │                       v     │
  │              │              ┌──────────┐   │
  │              │              │ Complete?│   │
  │              │              └────┬─────┘   │
  │              │                   │         │
  │              │         ┌────────┴────────┐│
  │              │         │                 ││
  │              v         v                 v│
  │         [Fix Issue]  [NO]            [YES]│
  │              │         │                 ││
  │              └─────────┘             EXIT │
  │                    │                      │
  └────────────────────┘                      │
                                              │
                                    <promise>COMPLETE</promise>

---

Setup Wizard

Phase 1: Project Selection

# Query Archon for projects
projects = find_projects(masters_only=True, include_hierarchy=True)

Present options:

## Select Project

| # | Project | Description | Tasks |
|---|---------|-------------|-------|
| 1 | [Project Name] | [Description] | [X] todo |
| 2 | [Project Name] | [Description] | [X] todo |

Enter project number (or 'new' to create):

Phase 2: Task Selection

# Get tasks for selected project
tasks = find_tasks(
    filter_by="project",
    filter_value=PROJECT_ID,
    include_closed=False
)

Present options:

## Select Task

### TODO Tasks (Recommended)
| # | Task | Feature | Priority |
|---|------|---------|----------|
| 1 | [Task Title] | [Feature] | [Order] |
| 2 | [Task Title] | [Feature] | [Order] |

### In Progress (Continue existing)
| # | Task | Feature | Assignee |
|---|------|---------|----------|
| 3 | [Task Title] | [Feature] | [Assignee] |

Enter task number (or 'new' to create, 'custom' for custom prompt):

Phase 3: Prompt Configuration

Auto-Generated Prompt Template:

# Ralph Loop: [TASK_TITLE]

## Objective
[From task description]

## Requirements
[Extracted from task]

## Acceptance Criteria
[From task if available]

## Self-Correction Loop

For each iteration:
1. Review previous work in files and git history
2. Run validation: `[TEST_COMMAND]`
3. If validation fails:
   - Analyze failure output
   - Fix the issue
   - Re-run validation
4. If validation passes:
   - Check against acceptance criteria
   - Continue to next requirement
5. When all requirements met:
   - Run full validation suite
   - Update Archon task to "done"
   - Output: <promise>COMPLETE</promise>

## Validation Commands
```bash
[BUILD_COMMAND]
[TEST_COMMAND]

Archon Context

• Project: [PROJECT_ID]
• Task: [TASK_ID]

Escape Hatch

After 15 iterations without progress:

1. Update Archon task with blocker details
2. Document what was attempted
3. Output: BLOCKED

### Phase 4: Options Configuration

```markdown
## Loop Options

### Iteration Limits
| Setting | Default | Your Choice |
|---------|---------|-------------|
| Max iterations | 50 | ___ |
| Timeout per iteration (min) | 0 (unlimited) | ___ |
| Pause between iterations (sec) | 0 | ___ |

### Completion Settings
| Setting | Default | Your Choice |
|---------|---------|-------------|
| Completion promise | "COMPLETE" | ___ |
| Complete on Archon task done | Yes | Yes / No |
| Complete on tests pass | No | Yes / No |

### Execution Mode
- [ ] **Background** - Fully autonomous (recommended for tested prompts)
- [ ] **Manual** - You trigger each iteration
- [ ] **Hybrid** - Start manual, then background (recommended)

### Validation Commands
| Type | Command | Auto-Detected |
|------|---------|---------------|
| Build | [detected] | Yes/No |
| Test | [detected] | Yes/No |
| Lint | [detected] | Yes/No |

Auto-Detection Logic

# Detect project type and commands
if [ -f "package.json" ]; then
    BUILD_CMD="npm run build"
    TEST_CMD="npm test"
    LINT_CMD="npm run lint"
elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
    BUILD_CMD="python -m build"
    TEST_CMD="pytest"
    LINT_CMD="ruff check ."
elif [ -f "*.csproj" ] || [ -f "*.sln" ]; then
    BUILD_CMD="dotnet build"
    TEST_CMD="dotnet test"
    LINT_CMD="dotnet format --verify-no-changes"
elif [ -f "go.mod" ]; then
    BUILD_CMD="go build ./..."
    TEST_CMD="go test ./..."
    LINT_CMD="golangci-lint run"
fi

---

Configuration Files

Directory Structure

.ralph/
├── config.json        # Loop configuration
├── prompts/
│   └── current.md     # Active iteration prompt
└── checkpoints/
    └── iteration-N.json  # State snapshots

config.json

{
  "loop_id": "ralph-2025-01-23-001",
  "archon_project_id": "<PROJECT_ID>",
  "archon_task_id": "<TASK_ID>",
  "prompt_file": ".ralph/prompts/current.md",
  "max_iterations": 50,
  "completion_promise": "COMPLETE",
  "mode": "hybrid",
  "validation": {
    "build": "npm run build",
    "test": "npm test",
    "lint": "npm run lint"
  },
  "integration": {
    "harness": false,
    "speckit": false,
    "prp": false
  }
}

---

Execution Commands

Command	Description
/ralph-setup	Launch setup wizard
/ralph-start	Create and start new loop
/ralph-iterate	Run single iteration (manual mode)
/ralph-continue	Resume background execution
/ralph-status	Check loop status
/ralph-cancel	Stop active loop

Quick Start Examples

# Full wizard
/ralph-setup

# Quick with defaults
/ralph-start --quick --project <id> --task <id>

# Auto mode (highest priority TODO task)
/ralph-start --auto

# Custom prompt without task
/ralph-start --custom "Implement feature X with tests"

---

Archon Integration

Create State Document

manage_document("create",
    project_id=PROJECT_ID,
    title=f"Ralph Loop State: {loop_id}",
    document_type="note",
    content={
        "loop_id": loop_id,
        "status": "running",
        "current_iteration": 0,
        "max_iterations": 50,
        "task_id": TASK_ID,
        "iterations": []
    }
)

Update Task on Start

manage_task("update",
    task_id=TASK_ID,
    status="doing",
    assignee="Ralph Agent",
    description=f"""[ORIGINAL_DESCRIPTION]

---
## Ralph Loop Attached
- Loop ID: {loop_id}
- Max Iterations: {max_iterations}
- Mode: {mode}
- Started: {timestamp}

Progress updates will appear here.
"""
)

Update on Completion

manage_task("update",
    task_id=TASK_ID,
    status="done",
    description=f"""[ORIGINAL_DESCRIPTION]

---
## Ralph Loop Complete
- Loop ID: {loop_id}
- Total Iterations: {iterations}
- Completed: {timestamp}

All acceptance criteria met.
"""
)

---

Iteration Protocol

Each Iteration Must:

1. Check Previous State

   • Read progress file
   • Check git history
   • Review Archon task

2. Execute Work

   • Make changes
   • Write code
   • Update files

3. Validate

   • Run build command
   • Run test command
   • Check lint (optional)

4. Handle Result

   • If PASS: Check completion criteria
   • If FAIL: Analyze error, fix, re-validate

5. Update State

   • Update progress file
   • Update Archon task
   • Git commit (if changes)

Completion Criteria

Loop ends when ANY of these are true:

• <promise>COMPLETE</promise> output
• All tests pass (if configured)
• Archon task status is "done"
• Max iterations reached
• <promise>BLOCKED</promise> output

---

Framework Integration

Ralph can integrate with other frameworks:

Framework	Integration Mode
Autonomous Harness	Ralph replaces coding loop
SpecKit	Ralph implements tasks from plan
PRP Framework	Ralph executes fix iterations

Detection

has_harness = exists(".harness/config.json")
has_speckit = exists(".specify/") or exists("specs/")
has_prp = exists("PRPs/")

---

Error Handling

No Archon Connection

Warning: Archon MCP Not Connected

Ralph requires Archon for state management. Please:
1. Verify Archon MCP server is configured
2. Check Archon server is running
3. Retry: /ralph-start

For standalone mode (not recommended):
/ralph-start --no-archon

Stuck Loop (No Progress)

After 15 iterations without meaningful progress:

manage_task("update",
    task_id=TASK_ID,
    status="review",
    description=f"""[ORIGINAL_DESCRIPTION]

---
## Ralph Loop BLOCKED
- Loop ID: {loop_id}
- Iterations Attempted: {iterations}
- Blocked At: {timestamp}

### What Was Attempted
{attempt_summary}

### Blocker Details
{blocker_description}

### Recommended Actions
{recommendations}

Requires human intervention.
"""
)

Output: <promise>BLOCKED</promise>

---

Best Practices

1. Clear Acceptance Criteria: Define what "done" looks like
2. Testable Validation: Use automated tests, not manual checks
3. Small Tasks: Break large work into Ralph-sized chunks
4. State Preservation: Always update Archon between iterations
5. Escape Hatches: Have clear blocker conditions
6. Git Commits: Commit after each successful iteration
7. Monitor Mode First: Use manual/hybrid before full background

---

Notes

• Ralph works best with well-defined, testable tasks
• Background mode requires high confidence in prompt quality
• Archon integration provides persistence across sessions
• Use escape hatches to prevent infinite loops
• Monitor resource usage in long-running loops