ralph-loop

name	ralph-loop
description	Self-diagnosing, self-correcting agent loop for Build phase. Defines DoD checking, inner/outer loop retry logic, circuit breakers, and sentinel health checks.
version	1.0.0

Ralph Loop Skill

A reusable self-diagnosing, self-correcting execution loop for the Build phase. Loaded by sdlc-build.md and sdlc-implement.md. Keeps token windows bounded by pinning only essential context on retries and routing targeted re-work rather than re-running everything.

---

Concepts

Term	Definition
DoD	Definition of Done — the acceptance criteria for a slice, taken from its scope.json entry
Slice	One independently verifiable unit of work (a row in scope.json.slices[])
Inner loop	Per-slice retry logic; runs inside the Build phase for each slice
Outer loop	Per-phase retry logic; runs once after qa-engineer's E2E pass
Sentinel	Lightweight health check that runs before the verification gateway to catch drift early
Circuit breaker	Hard limit on retries; surfaces failure to user rather than looping forever
Fresh context	Stripped-down context bundle assembled for each retry — no prior attempt reasoning

---

Inner Loop (per-slice)

Runs for every slice in scope.json.slices[], in order.

┌─────────────────────────────────────────────────────┐
│  SLICE N  ─  inner loop                             │
│                                                     │
│  1. Load DoD from scope.json slice entry            │
│  2. Assemble context bundle (see below)             │
│  3. SENTINEL CHECK ──► drift? → flag user, abort    │
│  4. fullstack-engineer executes slice               │
│  5. VERIFICATION GATEWAY                            │
│       run: typecheck + slice-scoped tests           │
│       PASS ──► append to implementation-log.md      │
│               advance to next slice                 │
│       FAIL ──► retry_count += 1                     │
│               retry_count ≤ 2? ──► reassemble       │
│                                     fresh context   │
│                                     goto step 3     │
│               retry_count > 2? ──► CIRCUIT BREAKER  │
│                                     surface to user │
└─────────────────────────────────────────────────────┘

Context Bundle (normal invocation)

Assembled once at the start of each slice:

• handoffs/plan-handoff.md — clean phase context (written at Plan gate)
• grill-summary.md — feature context and personas
• The slice's own entry from scope.json (id, name, type, layers, linear_id)
• implementation-log.md — what all previous slices built (read-only here)

Fresh Context Bundle (retry)

Assembled fresh for each retry attempt — no prior attempt reasoning, no prior conversation history:

• handoffs/plan-handoff.md
• grill-summary.md
• The slice's own entry from scope.json
• implementation-log.md (updated through the previous slice, not this one)
• Failure output pinned at the top — exact typecheck / test failure message from the last attempt

Circuit Breaker (inner)

After 2 retries exhausted and verification still failing:

1. Stop the loop immediately
2. Report to user:
   • Which slice failed (id, name)
   • The exact failure output from the last attempt
   • What was attempted (retry count, context used)
3. Await user decision — do not advance to the next slice

---

Sentinel (health check)

Runs before the verification gateway on every attempt (first run and retries). Checks for two forms of drift before wasting a full test run.

Context Drift

Signal: The implementation-log.md entry written for this slice is significantly shorter or vaguer than the entries written by previous slices.

Detection heuristic: If the new entry is <50% the word count of the median of all previous entries, or contains no file paths, no test counts, and no endpoint names — flag as context drift.

Action: Flag to user before retrying. Include the new entry and the median previous entry for comparison. Do not auto-retry on context drift — it usually means the agent lost the plot.

Spec Drift

Signal: Code written during execution does not match the layers declared in the slice entry.

Examples:

• Slice declares "layers": ["schema", "api"] but UI components were created
• Slice declares "layers": ["ui", "tests"] but migrations were written
• Slice declares "layers": ["tests"] but new business logic was introduced

Detection: After execution but before running tests, diff newly created/modified files against the declared layers:

• schema → expects changes in migrations/, models/, schema files only
• api → expects changes in controllers/, routes/, services/ only
• ui → expects changes in components/, pages/, frontend src/ only
• tests → expects changes in *.test.*, *.spec.*, e2e/ only

Action: Flag spec drift to user with a summary of what layers were touched vs. declared. Allow user to confirm before running tests (false positives are possible on scaffold slices).

---

Outer Loop (per-phase)

Runs once, after all feature slices complete and qa-engineer finishes its E2E pass.

┌─────────────────────────────────────────────────────┐
│  OUTER LOOP  ─  post-qa                             │
│                                                     │
│  1. qa-engineer runs E2E tests across all slices    │
│  2. All pass? ──► advance to Build gate             │
│  3. Some fail? ──► qa-engineer flags failing slices │
│  4. Targeted retry: only flagged slices re-enter    │
│       inner loop with E2E failure as feedback       │
│       (outer_retry_count = 1)                       │
│  5. After targeted retry, qa-engineer re-runs E2E   │
│  6. All pass? ──► advance to Build gate             │
│     Still failing? ──► CIRCUIT BREAKER              │
│                        surface to user              │
└─────────────────────────────────────────────────────┘

Targeted Retry Context

For each flagged slice in the outer loop retry, the fullstack-engineer receives fresh context (same bundle as inner loop fresh context) with the E2E failure output for that slice's flows pinned at the top. Slices not flagged by qa-engineer are not re-run.

Circuit Breaker (outer)

After 1 outer retry still failing:

1. Stop the outer loop
2. Report to user:
   • Which slices still have failing E2E tests
   • The exact E2E failure output
   • Which flows are broken (qa-engineer's summary)
3. Await user decision — do not proceed to Verify phase

---

implementation-log.md Format

Each slice appends one entry after passing the verification gateway:

## slice-N: <name>

- Files created/modified: path/to/file.ts, path/to/other.ts
- Endpoints added: POST /api/resource, GET /api/resource/:id
- Tables migrated: users, sessions
- Tests written: 12 unit tests, 3 integration tests
- Layers touched: schema, api

Slice 0 (prefactor) creates the file with its entry. All subsequent slices append. The file is read-only during a slice's execution and writable only after its verification gateway passes.

---

Applying This Skill — Checklist

When loading ralph-loop into a command or agent, verify:

• scope.json is present and slices array is non-empty
• grill-summary.md exists (Plan phase artifact)
• handoffs/plan-handoff.md exists (written at Plan gate)
• Inner loop is applied per-slice in slices[] order
• Sentinel runs before verification gateway on every attempt
• implementation-log.md is initialized by Slice 0 before feature slices begin
• Each slice receives only its own scope.json entry, not the full array
• Retry context is assembled fresh — no prior attempt reasoning
• Circuit breaker fires after 2 inner retries (not 3, not unlimited)
• Outer loop runs exactly once after qa-engineer's E2E pass
• Outer loop circuit breaker fires after 1 outer retry
• User is surfaced control at every circuit breaker — never auto-escalate or auto-skip

---

Integration Points

Command	How ralph-loop is used
sdlc-build.md	Wraps the fullstack-engineer invocation for each slice in the inner loop; runs outer loop after qa-engineer
sdlc-implement.md	Runs inner loop only (single slice / single spec); no outer loop (no qa-engineer phase)