home / skills / phrazzld / claude-config / ralph-patterns

ralph-patterns skill

safe

This skill helps you manage Ralph loop tasks by enforcing completion signals, progress updates, and iterative patterns to accelerate issue-to-PR flow.

npx playbooks add skill phrazzld/claude-config --skill ralph-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: ralph-patterns
description: |
  Patterns for Ralph loop tasks. Auto-loaded to provide guidance on
  completion signals, progress tracking, and iteration patterns.
  Ralph = autonomous issue-to-merged-PR loop.
user-invocable: false
effort: high
---

# Ralph Loop Patterns

You're running in a Ralph loop - an autonomous issue-to-merged-PR workflow.

## Completion Signals

Output these exact XML tags for the shell script to detect:

- `<promise>DONE</promise>` - Task complete, exit successfully
- `<promise>BLOCKED</promise>` - Cannot proceed, needs human intervention

Always include the exact XML tag. The shell script greps for it.

## Progress Tracking

Ralph monitors these for "no progress" circuit breaker:
- Git HEAD (commits)
- PR state (reviews, CI status)

**Make commits frequently to show progress.** Avoid long stretches without commits.

## Within a Ralph Loop

You have full access to:
- `/spec`, `/architect`, `/build`, `/refactor`, `/update-docs`, `/pr`
- Moonbridge MCP for Codex/Kimi delegation
- Sentry, PostHog, GitHub MCPs
- All configured hooks and skills

## Delegation Pattern

Use Moonbridge for implementation:
```
mcp__moonbridge__spawn_agent({
  "prompt": "Implement [feature]. Follow pattern in [ref file].",
  "adapter": "codex",
  "reasoning_effort": "high"
})
```

## Handling CI Failures

1. Get CI logs: `gh run view --log-failed`
2. Analyze failures
3. Fix and push
4. Wait for re-run (CI usually triggers automatically)

## Handling Review Feedback

1. Get PR comments: `gh pr view --comments`
2. Identify critical vs stylistic feedback
3. Address critical feedback first
4. Push changes
5. Respond to reviewers via commit message or PR comment

## When to Output BLOCKED

Output `<promise>BLOCKED</promise>` when:
- Missing required credentials or API keys
- Ambiguous requirements that need human clarification
- Conflicting constraints with no clear resolution
- External dependency is down/unavailable
- Permissions issues you can't resolve

Include a brief explanation after the tag:
```
<promise>BLOCKED</promise>
Reason: Need clarification on whether user auth should use JWT or session cookies.
```

## Anti-Patterns

- Don't loop infinitely on the same failing test
- Don't make empty commits just to show progress
- Don't ignore reviewer feedback hoping it goes away
- Don't skip /codify-learning at the end (Ralph does this automatically)

Overview

This skill provides patterns and practical guidance for running Ralph autonomous issue-to-merged-PR loops. It focuses on clear completion signals, progress tracking, delegation, CI and review handling, and when to surface human blockers. The guidance helps keep loops productive and auditable.

How this skill works

The skill defines exact XML completion tags that a supervising shell script expects and details when to emit each. It documents what signals Ralph watches for (commits, PR state, CI) and prescribes behaviors for delegation, CI failure handling, and responding to review feedback. It also lists common anti-patterns to avoid.

When to use it

When running an autonomous loop that must provide machine-detectable completion status.
When you need a consistent approach to show progress to a monitoring circuit breaker.
When delegating implementation tasks to Moonbridge/Codex agents.
When diagnosing CI failures or addressing reviewer feedback.
When deciding whether a situation requires human intervention (BLOCKED).

Best practices

Always output the exact XML tags <promise>DONE</promise> or <promise>BLOCKED</promise> for the shell script to detect.
Commit frequently and meaningfully to avoid 'no progress' circuit breakers; avoid empty commits.
Use Moonbridge delegation for heavy implementation work with a clear prompt and reference file.
Fetch CI failure logs, analyze root causes, fix, and push; wait for automatic CI re-runs.
Address critical review feedback first, then stylistic items; reply in PR comments or commit messages.
When blocked, emit <promise>BLOCKED</promise> plus a one-line reason to guide human intervention.

Example use cases

Autonomously implement a feature: delegate to Moonbridge, commit iteratively, finish with <promise>DONE</promise>.
Encounter a failing CI job: retrieve logs, fix the test or config, push a fix, and let CI re-run.
Receive ambiguous requirements: emit <promise>BLOCKED</promise> with a request for clarification.
Respond to review: classify comments, implement critical fixes, push updates, and notify reviewers.
Handle missing credentials: block with a clear reason and wait for human-supplied keys.

FAQ

What exact tags must I output for completion detection?

Output the exact XML tags <promise>DONE</promise> for success or <promise>BLOCKED</promise> when human help is required.

When should I emit BLOCKED instead of continuing?

Emit BLOCKED when essential credentials are missing, requirements are ambiguous, external dependencies are down, or permissions prevent progress; include a short reason.