| name | ralph-loop |
| description | Run, monitor, resume, merge, and debug Ralph loops. Use this skill whenever the user asks to operate `ralph run` or `ralph loops`, inspect loop state, recover suspended loops, analyze diagnostics, or unblock merge queue issues. |
Ralph Loop
Use this skill to operate Ralph loops from the outside.
Use This Skill For
- Starting or continuing a Ralph run with the right
-c and -H inputs
- Inspecting loop state, worktrees, logs, history, and diffs
- Resuming a hook-suspended loop
- Merging or discarding completed worktree loops
- Debugging unexpected loop behavior with current diagnostics files
Workflow
- Start with
ralph loops list or ralph loops list --json to establish the
current state.
- If the user wants execution, run
ralph run ... with the right core config
and hats source.
- If the loop is stuck or suspicious, inspect
logs, history, and diff
before changing state.
- If the loop is suspended, read
.ralph/suspend-state.json and use
ralph loops resume <id>.
- If a loop is queued or in
needs-review, inspect the diff first, then use
merge, process, retry, or discard as appropriate.
- Use diagnostics when you need detailed evidence about hats, events, tool
calls, parse errors, or performance.
Guardrails
- Prefer the CLI over direct edits to
.ralph state files.
- Treat tasks and memories as the canonical runtime systems; do not center
scratchpad as the primary state model.
- Inspect diffs before merging.
- Only remove lock or queue artifacts when the underlying process is confirmed
dead.
- Manual edits under
.ralph/ are last-resort recovery steps and should be
called out explicitly when used.
Read These References When Needed
- For command recipes and operator flows:
references/commands.md
- For diagnostics files and suspend-state details:
references/diagnostics.md
