/ralph

name: ralph
description: Self-referential loop until task completion with configurable verification reviewer
argument-hint: "[--no-deslop] [--critic=architect|critic|codex] <task description>"
level: 4

[RALPH - ITERATION {{ITERATION}}/{{MAX}}]

Your previous attempt did not output the completion promise. Continue working on the task.

<Purpose> Ralph is a PRD-driven persistence loop that keeps working on a task until ALL user stories in prd.json have passes: true and are reviewer-verified. It combines session persistence, automatic retry on failure, structured story tracking, and mandatory verification before completion. </Purpose>

<Use_When>

• Task requires guaranteed completion with verification (not just "do your best")
• User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
• Work may span multiple iterations and needs persistence across retries
• Task benefits from structured PRD-driven execution with reviewer sign-off

</Use_When>

<Do_Not_Use_When>

• User wants a full autonomous pipeline from idea to code -- use `autopilot` instead
• User wants to explore or plan before committing -- use `plan` skill instead
• User wants a quick one-shot fix -- delegate directly to an executor agent
• User wants manual control over completion -- delegate directly to an executor agent
• User already has an active Claude Code `/goal` and only wants that native goal loop monitored -- adopt the existing `/goal` explicitly or use artifact-only Ultragoal notes instead of starting Ralph as a competing persistence loop

</Do_Not_Use_When>

<Why_This_Exists> Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by:

1. Structuring work into discrete user stories with testable acceptance criteria (prd.json) 2. Iterating story-by-story until each one passes 3. Tracking progress and learnings across iterations (progress.txt) 4. Requiring fresh reviewer verification against specific acceptance criteria before completion </Why_This_Exists>

<PRD_Mode> By default, ralph operates in PRD mode. A scaffold `prd.json` is auto-generated when ralph starts if none exists. Active transient PRD state is session-scoped at `.omc/state/sessions/{sessionId}/prd.json` when a session ID is available; legacy project-level `prd.json` / `.omc/prd.json` files are read as startup migration inputs.

**Startup gate:** Ralph always initializes and validates `prd.json` at startup. Legacy `--no-prd` text is sanitized from the prompt for backward compatibility, but it no longer bypasses PRD creation or validation.

**Deslop opt-out:** If `{{PROMPT}}` contains `--no-deslop`, skip the mandatory post-review deslop pass entirely. Use this only when the cleanup pass is intentionally out of scope for the run.

**Reviewer selection:** Pass `--critic=architect`, `--critic=critic`, or `--critic=codex` in the Ralph prompt to choose the completion reviewer for that run. `architect` remains the default.

**Stale-state detection & reconciliation (#3669):** If a PRD is left unfinished by an abnormal/non-Step 8 exit (crash, force-kill, cancel before `/oh-my-claudecode:cancel`, session end), Ralph surfaces an explicit `[STALE PRD WARNING]` at startup/resume, in the continuation context, and at session end — with unfinished counts, last-touched age, and stale-pointer signals (PRD `branchName` merged/gone). Completion is NEVER inferred from PR/branch/merge status alone; git state is a warning signal only. A story is auto-reconciled to `passes: true` ONLY when the PRD carries configured observable evidence and every check passes:

{
  "reconciliation": {
    "staleAfterMs": 7200000,
    "observableChecks": {
      "US-001": [
        { "type": "fileContains", "path": "src/landed.ts", "pattern": "LANDED_SYMBOL" },
        { "type": "gitGrep", "ref": "origin/dev", "pattern": "LANDED_SYMBOL" }
      ]
    }
  }
}

Check types: `fileExists` / `fileContains` (working tree) and `gitGrep` (content at a ref — this is "verified by content on trunk", never PR status). Stories without configured checks are never auto-marked. Reconciled stories keep `architectVerified: false` and still require Step 7 reviewer verification before Step 8; every decision is appended to the `prd-reconciliation.jsonl` audit log and summarized in the story notes. </PRD_Mode>

<PRD_Criterion_Amendments> Acceptance criteria are the PRD's completion authority: Step 4 verifies EACH active criterion and Step 7 reviews against them. A criterion can stop governing ONLY through the evidence-preserving amendment path — never by silent deletion or by "satisfying" a criterion measurement has refuted.

When implementation proves a criterion empirically false (e.g. a count in the dispatching brief is wrong), amend it:

1. **Replace** the refuted criterion with the measured correction, or **supersede** it when no replacement governs. 2. Record the amendment in the story's `criterionAmendments` ledger. The original criterion text is retained verbatim (never rewritten or deleted) alongside:

• `kind`: `"replaced"` or `"superseded"`
• `original`: the verbatim refuted criterion (must still be active when the amendment is recorded)
• `replacement`: the corrected criterion (only for `replaced`)
• `reason`: why the original no longer governs
• `evidence`: the bounded measurement that refuted it (e.g. "enumerated 12 setters, not 16: ...")
• `authority`: who made the amendment (use the ralph session id)
• `timestamp`: ISO 8601 timestamp

3. The completion check then verifies only the ACTIVE criteria; the ledger keeps the audit trail so reviewers see why the original no longer governs.

Rules:

• An amendment without bounded evidence, reason, authority, or timestamp is invalid — the PRD fails closed on read rather than being silently weakened.
• An original that is still active cannot be amended; an original can be amended only once.
• Progra