dev-ralph

Iterate software engineering tasks until a defined completion signal or circuit breaker stops.

520|175|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/EvolutionAPI/evo-nexus --skill dev-ralph
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: dev-ralph
Source: https://github.com/EvolutionAPI/evo-nexus/tree/main/.claude/skills/dev-ralph
Command: npx skills add https://github.com/EvolutionAPI/evo-nexus --skill dev-ralph

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Persistence loop. Keep iterating on a task until it's resolved, with a circuit breaker for safety. Different from /loop (which is time-based) — ralph runs the same agent repeatedly until a goal is met.

Core Features & Use Cases

  • Use When: Task has a clear completion signal but iteration count is unknown; you want to progressively refine results.
  • Do Not Use When: You require time-based polling or a single-shot operation.
  • Iron Rules:
    1. Completion signal must be defined upfront.
    2. Circuit breaker: stop after 5 iterations OR after 3 identical failures.
    3. State persisted between iterations.
    4. Never silently spin — emit progress every iteration.
  • Workflow:
    • Iteration 1: Run agent, check completion, record attempts and results, increment counter.
    • Iteration 2..N: Run with accumulated state; continue until completion or breaker.
    • On max iterations or repeated failures: Stop and escalate with full state.
  • Output: Per iteration, emit a structured log with iteration number, goal, attempted actions, result, and current state. Final report saved to workspace/development/debug/[C]ralph-{topic}-{date}.md.

Quick Start

Initiate a ralph loop by defining a clear completion signal and the initial task, then let it iterate until the signal is met or a circuit breaker halts progress.

Frequently Asked Questions about dev-ralph

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate iterative task refinement until a bug fix is complete?

To automate iterative task refinement, define a clear completion signal upfront and let the persistence loop run the same agent repeatedly. State is persisted between iterations until the goal is met or a circuit breaker halts progress.

How does a circuit breaker stop unproductive loops in automated debugging?

A circuit breaker stops unproductive loops by enforcing a maximum iteration count of 5 or halting after 3 identical failures. This prevents infinite spinning and escalates with full accumulated state when limits are reached.

When should I use a persistence loop instead of time-based polling for feature refinement?

Use a persistence loop for feature refinement when a task has a clear completion signal but the required iteration count is unknown. Avoid it if you need time-based polling or a single-shot operation without progressive state accumulation.

What is logged during each iteration of an automated engineering workflow?

Each iteration of an engineering workflow logs the iteration number, goal, attempted actions, result, and current state. This structured log ensures the process never silently spins and records progressive refinement attempts.

How do I define a completion signal for an automated bug fixing loop?

Defining a completion signal for an automated bug fixing loop requires specifying the exact success criteria upfront before iteration begins. The loop continuously evaluates agent results against this signal to determine if the task is resolved.

What happens when an iterative task refinement loop exceeds maximum iterations?

When iterative task refinement exceeds maximum iterations or repeated failures, the circuit breaker stops the loop and escalates with full state. The final report is saved to workspace/development/debug/ with the topic and date.