ralph_loop

[RALPH LOOP - ITERATION {{ITERATION}}/{{MAX}}]

Your previous attempt did not output the completion promise. Continue working on the task.

<Use_When>

• Task requires guaranteed completion with verification (not just "do your best")
• User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
• Work may span multiple iterations and needs persistence across retries
• Task benefits from parallel execution with architect sign-off at the end </Use_When>

<Do_Not_Use_When>

• User wants a full autonomous pipeline from idea to code -- use autopilot instead
• User wants to explore or plan before committing -- use plan skill instead
• User wants a quick one-shot fix -- delegate directly to an executor agent
• User wants manual control over completion -- use ultrawork directly </Do_Not_Use_When>

<Why_This_Exists> Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by looping until work is genuinely complete, requiring fresh verification evidence before allowing completion, and using tiered architect review to confirm quality. </Why_This_Exists>

<Execution_Policy>

• Fire independent agent calls simultaneously -- never wait sequentially for independent work
• Use run_in_background: true for long operations (installs, builds, test suites)
• Always pass the model parameter explicitly when delegating to agents
• Deliver the full implementation: no scope reduction, no partial completion, no deleting tests to make them pass
• Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail
• Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints
• If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the execution loop is grounded
• Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent </Execution_Policy>

<Tool_Usage>

• Before first MCP tool use, call ToolSearch("mcp") to discover deferred MCP tools
• Use architect verification when changes are security-sensitive, architectural, or involve complex multi-system integration
• Skip architect consultation for simple feature additions, well-tested changes, or time-critical verification
• Use state persistence tools for ralph mode state between iterations
• Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context </Tool_Usage>

State Management

Use the state MCP server tools or file-based state for Ralph lifecycle state:

• On start: Write state with mode: "ralph", active: true, iteration: 1, max_iterations: 10
• On each iteration: Update iteration count and current phase
• On completion: Mark as complete and cleanup
• On cancellation: Clear all state files

Scenario Examples

Good: The user says continue after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.

Good: The user changes only the output shape or downstream delivery step. Preserve earlier non-conflicting workflow constraints and apply the update locally.

Bad: The user says continue, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.

<Escalation_And_Stop_Conditions>

• Stop and report when a fundamental blocker requires user input (missing credentials, unclear requirements, external service down)
• Stop when the user says "stop", "cancel", or "abort"
• Continue working when iteration continues
• If architect rejects verification, fix the issues and re-verify (do not stop)
• If the same issue recurs across 3+ iterations, report it as a potential fundamental problem </Escalation_And_Stop_Conditions>

<Final_Checklist>

• All requirements from the original task are met (no scope reduction)
• Zero pending or in_progress TODO items
• Fresh test run output shows all tests pass
• Fresh build/lint output shows success
• Architect verification passed (STANDARD tier minimum)
• ai-slop-cleaner pass completed on changed files (or --no-deslop specified)
• Post-deslop regression tests pass </Final_Checklist>

When the user provides the --prd flag, initialize a Product Requirements Document before starting the ralph loop.

Detecting PRD Mode

Check if the prompt contains --prd or --PRD.

Detecting --no-deslop

Check if the prompt contains --no-deslop. If present, skip the deslop pass.

Visual Reference Flags (Optional)

Ralph execution supports visual reference flags for screenshot tasks:

• Image inputs: -i <image-path>
• Image directory input: --images-dir <directory>

PRD Workflow

1. Parse the task (everything after --prd flag)
2. Create canonical PRD artifacts:
   • PRD: .clawd/plans/prd-{slug}.md
   • Progress ledger: .clawd/state/ralph-progress.json
3. Break down into user stories with acceptance criteria
4. Initialize progress ledger
5. Proceed to normal ralph loop using user stories as the task list

Background Execution Rules

Run in background (run_in_background: true):

• Package installation (pip install, cargo build)
• Build processes (make, project build commands)
• Test suites
• Docker operations (docker build, docker pull)

Run blocking (foreground):

• Quick status checks (git status, ls, pwd)
• File reads and edits
• Simple commands</Advanced>

Original task: {{PROMPT}}