--- name: ralph-operations-8433c8e58d34 description: Use when managing Ralph orchestration loops, analyzing diagnostic data, debugging hat selection, investigating backpressure, or performing post-mortem analysis tags: [loops, diagnostics, debugging, analysis] --- # Ralph Operations Manage, monitor, and diagnose Ralph orchestration loops. ## Loop Management ### Quick Reference | Task | Command | |------|---------| | List active loops | `ralph loops` | | List all (including merged) | `ralph loops --all` | | View loop changes | `ralph loops diff ` | | View loop logs | `ralph loops logs ` | | Follow logs live | `ralph loops logs -f` | | Stop running loop | `ralph loops stop ` | | Merge completed loop | `ralph loops merge ` | | Retry failed merge | `ralph loops retry ` | | Abandon loop | `ralph loops discard ` | | Clean stale processes | `ralph loops prune` | **Loop ID format:** Partial matching works - `a3f2` matches `loop-20250124-143052-a3f2` ### Loop Status | Status | Color | Meaning | |--------|-------|---------| | running | green | Loop is actively executing | | queued | blue | Completed, waiting for merge | | merging | yellow | Merge in progress | | needs-review | red | Merge failed, requires intervention | | merged | dim | Successfully merged (with `--all`) | | discarded | dim | Abandoned (with `--all`) | ### Starting & Stopping Loops start automatically via `ralph run`: - **Primary loop**: Runs in main workspace, holds `.ralph/loop.lock` - **Worktree loop**: Created when primary is running, isolated in `.worktrees//` ```bash ralph loops # Any loops running? cat .ralph/loop.lock 2>/dev/null # Primary loop details ralph loops stop # Graceful stop ralph loops stop --force # Immediate stop ralph loops discard # Abandon + clean worktree ``` ### Inspecting Loops ```bash ralph loops diff # What changed ralph loops logs -f # Live event log ralph loops history # State changes ralph loops attach # Shell into worktree ``` **Worktree context files** (`.worktrees//`): | File | Contents | |------|----------| | `.ralph/events.jsonl` | Event stream: hats, iterations, tool calls | | `.ralph/agent/summary.md` | Current session summary | | `.ralph/agent/handoff.md` | Handoff context for next iteration | | `.ralph/agent/scratchpad.md` | Working notes | | `.ralph/agent/tasks.jsonl` | Runtime task state | **Primary loop** uses the same files at `.ralph/agent/` in repo root. ### Merge Queue Flow: `Queued → Merging → Merged` or `→ NeedsReview → Merging (retry)` or `→ Discarded` ```bash ralph loops merge # Queue for merge ralph loops process # Process pending merges now ralph loops retry # Retry failed merge ``` **Reading state:** ```bash jq -r '.prompt' .ralph/loop.lock 2>/dev/null tail -20 .ralph/merge-queue.jsonl | jq . ``` --- ## Diagnostics ### Enabling ```bash RALPH_DIAGNOSTICS=1 ralph run -p "your prompt" ``` Zero overhead when disabled. Output: `.ralph/diagnostics//` ### Session Discovery ```bash LATEST=$(ls -t .ralph/diagnostics/ | head -1) SESSION=".ralph/diagnostics/$LATEST" ``` ### File Reference | File | Contains | Key Fields | |------|----------|------------| | `agent-output.jsonl` | Agent text, tool calls, results | `type`, `iteration`, `hat` | | `orchestration.jsonl` | Hat selection, events, backpressure | `event.type`, `iteration`, `hat` | | `performance.jsonl` | Timing, latency, token counts | `metric.type`, `iteration`, `hat` | | `errors.jsonl` | Parse errors, validation failures | `error_type`, `message`, `context` | | `trace.jsonl` | All tracing logs with metadata | `level`, `target`, `message` | ### Diagnostic Workflow **1. Errors first:** ```bash wc -l "$SESSION/errors.jsonl" jq '.' "$SESSION/errors.jsonl" jq -s 'group_by(.error_type) | map({type: .[0].error_type, count: length})' "$SESSION/errors.jsonl" ``` **2. Orchestration flow:** ```bash jq '{iter: .iteration, hat: .hat, event: .event.type}' "$SESSION/orchestration.jsonl" jq 'select(.event.type == "hat_selected") | {iter: .iteration, hat: .event.hat, reason: .event.reason}' "$SESSION/orchestration.jsonl" jq 'select(.event.type == "backpressure_triggered") | {iter: .iteration, reason: .event.reason}' "$SESSION/orchestration.jsonl" ``` **3. Agent activity:** ```bash jq 'select(.type == "tool_call") | {iter: .iteration, tool: .name}' "$SESSION/agent-output.jsonl" jq -s '[.[] | select(.type == "tool_call")] | group_by(.iteration) | map({iter: .[0].iteration, tools: [.[].name]})' "$SESSION/agent-output.jsonl" ``` **4. Performance:** ```bash jq 'select(.metric.type == "iteration_duration") | {iter: .iteration, ms: .metric.duration_ms}' "$SESSION/performance.jsonl" jq -s '[.[] | select(.metric.type == "token_count")] | {total_in: (map(.metric.input) | add), total_out: (map(.metric.output) | add)}' "$SESSION/performance.jsonl" ``` **5. Trace logs:** ```bash jq 'select(.level == "ERROR" or .level == "WARN")' "$SESSION/trace.jsonl" ``` ### Quick Health Check ```bash SESSION=".ralph/diagnostics/$(ls -t .ralph/diagnostics/ | head -1)" echo "=== Session: $SESSION ===" echo -e "\n--- Errors ---" wc -l < "$SESSION/errors.jsonl" 2>/dev/null || echo "0" echo -e "\n--- Iterations ---" jq -s 'map(select(.event.type == "iteration_started")) | length' "$SESSION/orchestration.jsonl" echo -e "\n--- Hats Used ---" jq -s '[.[] | select(.event.type == "hat_selected") | .event.hat] | unique' "$SESSION/orchestration.jsonl" echo -e "\n--- Backpressure Count ---" jq -s 'map(select(.event.type == "backpressure_triggered")) | length' "$SESSION/orchestration.jsonl" echo -e "\n--- Termination ---" jq 'select(.event.type == "loop_terminated")' "$SESSION/orchestration.jsonl" ``` --- ## Troubleshooting ### Stale Processes `ralph loops` shows loops that aren't running → `ralph loops prune` ### Orphan Worktrees `.worktrees/` has directories not in `ralph loops` → `ralph loops prune` or `git worktree remove .worktrees/ --force` ### Merge Conflicts Loop stuck in `needs-review`: 1. `ralph loops diff ` — see conflicting changes 2. `ralph loops attach ` — resolve manually, commit, retry 3. `ralph loops discard ` — abandon if not worth fixing ### Lock Stuck "Loop already running" but nothing is → `rm .ralph/loop.lock` (safe if process is dead) ### Agent Stuck in Loop ```bash jq -s '[.[] | select(.type == "tool_call")] | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)' "$SESSION/agent-output.jsonl" ``` Red flag: Many iterations with few events = agent not making progress. ### Merge Stuck in "merging" Process died mid-merge. Unblock: ```bash echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%S.000000Z)'","loop_id":"","event":{"type":"needs_review","reason":"Merge process died"}}' >> .ralph/merge-queue.jsonl ralph loops discard ``` ### Worktree Corruption ```bash git worktree repair ralph loops prune ``` ### Cleanup ```bash ralph clean --diagnostics # Delete all sessions ralph clean --diagnostics --dry-run # Preview deletions ``` --- Source attribution: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/paulpete/ralph-operations/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 clawdbot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/paulpete/ralph-operations/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Development & Engineering, Product Management Roles: Backend Developer, Data Analyst, DevOps / SRE, ML / AI Engineer, Product Manager Specialties: API, Backend Tools: Ralph Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 8f8703052b4b0da9f88904985720bbeb5befc3624e3a164662237bfcb95e1f56