| name | potato:update-ralph-loop |
| description | Use this to update the status of a ralph loop status for any iterative workflow. Controls whether to continue iterating, complete successfully, or escalate when blocked. |
Updating Ralph Loop
The Rule
When your review is complete, call the ralph_loop_dock immediately. Not after cleanup. Not after one more check. Immediately.
Review done → ralph_loop_dock() → Nothing else
The Tool
ralph_loop_dock({
approved: boolean,
feedback?: string
})
When to Approve
Call ralph_loop_dock({ approved: true }) when:
- All requirements are met
- Tests pass
- No blocking issues remain
When to Reject
Call ralph_loop_dock({ approved: false, feedback: "..." }) when work needs revision.
Your feedback is injected into the next iteration. The builder will see exactly what you wrote. Be specific. Be actionable.
| Bad Feedback | Good Feedback |
|---|
| "Needs work" | "Missing error handling for network timeouts in fetchUser()" |
| "Tests incomplete" | "No tests for edge case: empty input array in processItems()" |
| "Not quite right" | "Button placement violates design spec - should be right-aligned per mockup" |
When to Block
If you cannot approve AND revision won't help (missing requirements, need user input, fundamental design question), still call:
ralph_loop_dock({
approved: false,
feedback:
"BLOCKED: Cannot proceed without user clarification on auth strategy",
});
The system handles escalation. Your job is to signal.
Red Flags - STOP Immediately
These thoughts mean you're avoiding the tool:
| Thought | Reality |
|---|
| "I'll just note this in the code" | Notes don't signal the orchestrator. Call the tool. |
| "The exit code will handle it" | Exit codes lose your feedback. Call the tool. |
| "I need to do one more thing first" | Review is done when review is done. Call the tool now. |
| "This is obvious, no feedback needed" | If rejected, feedback is required. Always explain why. |
The Contract
- One call per review - Call
ralph_loop_dock exactly once at the end of your review
- Feedback on rejection - If
approved: false, explain what's wrong
- No file updates - The tool handles storage. Don't write to ralph loop files.
- Immediate call - When your verdict is clear, call immediately
What Happens Next
- Approved: Loop completes, phase advances
- Rejected + attempts remain: Builder gets your feedback, tries again
- Rejected + max attempts: Ticket blocks, user notified
Your feedback directly shapes the next iteration. Make it count.
