Ralph-loop when loop-shaped — reach for the primitive, not another one-shot

rule Sat Jul 04 2026 00:00:00 GMT+0000 (Coordinated Universal Time) agentloopskillsorchestrationralph

Ralph-loop when loop-shaped

The rule

When a task fits the loop-shape criteria below, invoke ralph-loop (skill) or one of its presets. Don't reinvent the loop each turn. Don't hand-roll a for-each in the main thread when the primitive is available.

Loop-shape criteria (all must hold)

1. Task decomposes into repeatable iterations
2. Task-done predicate is expressible (a search returns empty; a checklist empties; a test passes)
3. Iteration cost is small vs main-thread context growth
4. Bounded time budget acceptable
5. Failure of one iteration does not require aborting the loop

When to invoke

Recognizable patterns that ARE loop-shaped:

• Audit fanout: "review every X for Y" (starred repos, own submodules, SOFA Qs, files matching pattern)
• Find-fix-verify: "find all instances of X, fix each, verify each"
• Inventory sweep: "enumerate candidates, dedup, act per candidate, checkpoint"
• Batch API calls: "for each of N items, call remote service with backoff"
• Refactor sweep: "for every match of pattern P, apply transformation T"
• Async fanout with aggregation: "gather N subagent findings, synthesize"

Anti-patterns that are NOT loop-shaped:

• Single-file edit with known path (just Edit)
• Fuzzy "make X better" (no expressible done-predicate)
• Task with irreversible per-iter side effects (paid API, non-refundable actions)
• Task where user wants to steer every step

Preset > Custom > Skip-and-invent

Order of preference:

1. Existing preset (check agent-skills/* for a preset matching the shape) — best: reuses defaults, memory-file conventions, and cross-refs
2. Custom ralph-loop invocation — invoke ralph-loop skill with task-specific args
3. Hand-rolled loop in-workflow — only if the task shape truly doesn't fit either

Available presets (2026-07-04)

• starred-repo-audit — GH starred-list fanout
• own-repo-health-check — chirag127/* repo maintenance sweep
• own-repos-audit-loop — filesystem-side submodule audit
• sofa-q-fanout — SOFA-Q push loop
• sofa-answer-triage — SOFA-answer pull loop

Autonomy inheritance

Ralph loop runs at the autonomy level the invoker was authorized for. External writes (issues, PRs, SOFA posts) inherit standing-auth. Standing-auth exceptions still apply:

• Paid API calls
• Repo deletions / transfers
• Mass deletions ≥50 LOC
• Any action currently gated in AGENTS.md

Loop must halt + surface for MCQ on any of the above.

Anti-patterns

• ❌ Hand-rolling a for-each over 50 items in the main thread when a workflow subagent fanout would cost 1/10 the context
• ❌ Invoking the loop primitive when the task is genuinely one-shot (over-engineering)
• ❌ Ignoring the presets and re-inventing a starred-repo audit or SOFA-Q fanout from scratch
• ❌ Setting no stop condition — every loop has a wall-clock cap and an iter cap AND a task-done predicate
• ❌ Skipping the memory-file checkpoint — even a 3-iter loop benefits from .loop-state.md for post-mortem

Cross-refs

• delegate-to-subagents-by-default — subagent-per-iter is the default beyond iter 3
• sofa-workflow — SOFA is a natural ralph-loop target (two presets already)
• no-deferral-until-complete — loop must finish its inventory in the invocation
• minimum-everything — loops still respect per-task budgets