Skip to content

xpepper/pr-review-agent-skill / ralph-wiggum-loop

ralph-wiggum-loop

Verified

Use when context window exhaustion is a concern or when addressing a large volume of PR comments — spawns a fresh agent session per comment via an external shell loop. For an in-session approach, use pr-review-loop or copilot-review-loop instead.

FileKindSize
CODE_REVIEW_PLAN.mdmarkdown6.1 KB
README.mdmarkdown2.5 KB
SKILL.mdskill md3.7 KB
# Ralph Wiggum Loop

An [Agent Skills](https://agentskills.io) skill implementing the
[Ralph Wiggum pattern](https://ghuntley.com/ralph/): an external shell loop that
spawns a fresh agent session per PR comment. Each invocation does exactly one unit
of work (triage or fix one comment), then stops. The shell loop handles repetition.

Works with any agent that accepts piped instructions.

> [!NOTE]
> For a user-controlled workflow that pauses after triage and after every
> comment so you can start each fresh session manually, use the experimental
> `/pr-review-loop --handoff` mode instead. Ralph remains the unattended
> external-loop option and does not yet share that handoff protocol.

## Why this pattern?

- Each session is minimal — no context window exhaustion
- Stateless agent, stateful files — resume after any failure by restarting the loop
- Agent-agnostic — works with Claude, Codex, Cursor, or any future agent
- Transparent — `PR_COMMENTS_PLAN.md` shows exactly what's done and what's pending

## Usage

This skill is not invoked via chat. You run a shell loop in your terminal —
the loop is the invocation:

```bash
# Claude
while [ ! -f PR_REVIEW_DONE ]; do
  cat CODE_REVIEW_PLAN.md | claude -p --dangerously-skip-permissions
done

# Codex
while [ ! -f PR_REVIEW_DONE ]; do
  cat CODE_REVIEW_PLAN.md | codex exec --yolo -
done
```

See **Setup** below to get `CODE_REVIEW_PLAN.md` into your project first.

## Setup

### 1. Install the skill

```bash
npx skills add xpepper/pr-review-agent-skill/ralph-wiggum-loop -a claude-code
```

### 2. Copy the plan file to your project root

```bash
cp ~/.claude/skills/ralph-wiggum-loop/CODE_REVIEW_PLAN.md .
```

### 3. Optionally gitignore the working files

```gitignore
CODE_REVIEW_PLAN.md
PR_COMMENTS_PLAN.md
PR_REVIEW_DONE
.pr-review/
```

### 4. Run the loop

```bash
# Claude
while [ ! -f PR_REVIEW_DONE ]; do
  cat CODE_REVIEW_PLAN.md | claude -p --dangerously-skip-permissions
done

# Codex
while [ ! -f PR_REVIEW_DONE ]; do
  cat CODE_REVIEW_PLAN.md | codex exec --yolo -
done
```

## How it works

| Iteration | What the agent does |
|-----------|---------------------|
| 1st | Fetches all PR comments, triages them, writes `PR_COMMENTS_PLAN.md` |
| 2nd–N | Fixes the topmost unresolved comment (MUST_FIX first, then SHOULD_FIX) |
| Final | Writes `PR_REVIEW_DONE` → loop terminates |

## Prerequisites

- `gh` CLI authenticated to GitHub
- PR branch checked out locally

## Cleanup

```bash
rm -f CODE_REVIEW_PLAN.md PR_COMMENTS_PLAN.md PR_REVIEW_DONE
rm -rf .pr-review/
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall