RALPH Loop

RALPH packages the recurring multi-LLM hardening sweep:

Recon the codebase → Assemble a review packet → Launch diverse reviewers → Patch proven findings → Handoff learnings.

Use it when the user asks for another sweep, a tough multi-LLM review, recurring codebase hardening, or “keep looking for untouched areas.” It extends second-opinions: that skill validates one change or decision; RALPH repeatedly searches the repo for the next highest-leverage surface and turns reviewer output into fixes, docs, and follow-up work.

Operating stance

Be tough but fair. External models are collaborators, not judges. Prefer fixes that are:

• correctness, security, data loss, auth, or observability issues;
• small and locally testable;
• aligned with project conventions;
• safe for users and support teams.

Reject reviewer suggestions that are stale, hallucinated, over-engineered, already fixed, or require product decisions.

External model CLIs (ask first)

In-session subagents need no extra permission and are the default for every role below. Launching a separate agent CLI (claude -p, codex exec, omp -p, pi -p) is different: it spends the user's quota and sends project content to that provider. Before the first launch:

1. Read ${XDG_CONFIG_HOME:-$HOME/.config}/agent-skills/external-clis.json if it exists. A CLI listed under skills.ralph-loop.allow or top-level allow may run without asking; one listed under deny (either level) must not run. Skill-level entries win.
2. Otherwise run command -v claude codex omp pi, then ask once: which installed CLIs may this skill launch, and should the answer apply to this run, always for this skill, or always?
3. For "always", create or update the file (merge; never drop other skills' entries), e.g. {"allow": ["codex"], "deny": [], "skills": {"ralph-loop": {"allow": ["claude", "codex"]}}}.
4. Bound every call (timeout 600 ...). Report which CLI and model actually answered. If none ran, say the outside cross-check did not happen rather than presenting subagent output as one.

Equivalent one-shot forms: claude -p --model <m> "<prompt>", codex exec -m <m> --sandbox read-only "<prompt>", omp -p --model <m> "<prompt>", pi -p "<prompt>". Prefer a CLI from a different company than the current session for outsider roles. Pick a capability tier, not a pinned model name: fast, balanced, or strongest. Use each CLI's current model list or default to map the tier; omit --model if unsure.

Loop shape

1. Recon — choose the next frontier

Start from repo evidence, not vibes.

1. Read project instructions.
2. Check git status and issue tracker.
3. Inspect recent commits/docs/review artifacts to avoid repeating the same modules.
4. Build a frontier map of code not yet swept or newly changed.

Good frontier slices:

• user-facing views/forms/API/auth;
• background tasks/schedulers/importers;
• integrations/OAuth/webhooks/external APIs;
• billing/security/permissions;
• data sync/migrations/admin commands;
• LLM/tool-calling surfaces;
• observability and Sentry/error-handling seams;
• tests that imply important behavior but lack coverage.

If the repo has prior review docs, append “already swept” and “next frontier” notes to avoid orbiting the same planet until the flamingo gets dizzy.

2. Assemble — create a bounded review packet

Prefer the bundled prompt builder:

uv run <skill-dir>/scripts/build_ralph_prompt.py --focus "views, API, auth" --out-dir "${TMPDIR:-/tmp}/ralph-$(basename "$PWD")"

<skill-dir> is this skill's directory; if the script cannot be found, build the packet manually.

The packet should include:

• repo/product context in 5–10 lines;
• previous sweep summary or paths to review docs;
• selected file/function/error map;
• bounded excerpts, not whole giant files;
• explicit review criteria:
  • Must-fix / Should-fix / Nice-to-have / Reject;
  • correctness, refactoring, performance, security, Sentry/context;
  • user-safe errors and no secrets/PII in logs or events;
  • “small actionable fixes only.”

Keep prompts under shell argument limits. If using a CLI wrapper that passes prompt as argv, aim for <50k chars.

3. Launch — fan out reviewers

Use at least three differentiated review prompts when the change warrants it: architecture and hard correctness (strongest tier), practical bug hunting (balanced), and a fast blunt edge-case pass (fast). Default to in-session subagents at those tiers. Add outside model CLIs only per the policy above, preferring a different company than the current session for at least one reviewer. Prompt diversity matters more than pretending three wrappers are three independent judges.

Run reviewers in parallel when tools allow. Store raw outputs outside the repo (the user's notes dir if named, otherwise a temp dir) with model and date in the filename.

Prompt reviewers to include file/function, reason, suggested fix, severity, and a Reject/Do-not-do section.

4. Synthesize — classify with skepticism

Create a synthesis table:

Important checks:

• Verify every alleged bug against actual source.
• Reproduce or reason through failures before patching.
• Watch for “reviewer line numbers” that are approximate or stale.
• If a reviewer says “syntax error,” run compile/tests before believing it.
• For Sentry fixes, capture enough context to debug but avoid raw emails, phone numbers, OAuth states, webhook URLs, passwords, tokens, service-account paths, or provider payloads.

5. Patch — apply only high-confidence work

Use normal project workflow and issue tracking. Patch in small commits if possible.

Common RALPH fix patterns:

• Replace raw user-facing str(exc) with generic copy + Sentry capture.
• Add scoped Sentry tags/context: feature, operation, safe ids, model/provider, status code.
• Hash/fingerprint sensitive correlators instead of logging raw values.
• Add per-item exception isolation in batch loops where one bad item should not abort all users.
• Validate query params and enum-like POST values before service calls.
• Debounce high-frequency writes from polling clients.
• Convert silent fallback into “fallback + observable event.”
• Add targeted tests for each fixed edge.

6. Harden docs — preserve the mental path

Create a review doc in the repo when appropriate:

docs/reviews/YYYY-MM-DD-ralph-<frontier>-review.md

Include:

• models used;
• scope/frontier;
• raw artifact paths;
• accepted fixes;
• deferred candidates;
• rejected findings and why;
• one “product learning” or operating rule.

Update core project instructions only for durable learnings that future agents should obey.

7. Validate, land, handoff

Run targeted tests plus the repo’s standard gates. Commit, push, close issue(s). Final answer should be concise:

• commit hash;
• frontier reviewed;
• models used;
• fixes applied;
• tests run;
• next sweep frontier if obvious.

RALPH stop rule

Keep looping while each pass finds meaningful, distinct fixes. Stop or switch strategy when:

• reviewers mostly repeat prior findings;
• suggestions are architectural/product decisions, not hardening;
• the next frontier needs domain input;
• test debt or design debt is now more important than more review.

When stopping, name the next higher-leverage move: test suite expansion, architecture split, threat model, performance profile, visual QA, launch-sequence, etc.

Relationship to other skills

• Use second-opinions inside RALPH for reviewer fan-out and classification discipline.
• Use wide-open-brainstorm only when reviewer output reveals product/UX direction rather than concrete code hardening.
• Use trust-audit when findings cluster around privacy, permissions, auth, or destructive actions.
• Use empathy-audit when findings cluster around confusing UX, support burden, machine load, or developer maintainability.