Ralph

# /ralph — Execute Ralph Loop for a Task

Execute the Ralph Loop (PRD §16) for the task specified below.

**Task:** $ARGUMENTS

## Instructions

1. **READ** `tasks/$ARGUMENTS.md` (or search `tasks/` for the matching T-NNNN file).
2. **READ** `PRD.md` sections referenced in the task's `PRD-ref` field.
3. **READ** `.claude/runs/` for any prior state on this task.
4. **WRITE** `.claude/runs/<ISO8601_timestamp>/state.json` with initial plan:

```json
{
  "task_id": "<T-NNNN>",
  "started_at": "<ISO8601>",
  "iteration": 1,
  "subtasks": [],
  "status": "planning"
}

5. DECOMPOSE the task into subtasks ≤ 4 hours each. If a subtask is > 4h, split it and update the task file.

6. ROUTE each subtask to the correct subagent per AGENTS.md and PRD §15 routing matrix.

7. VERIFY each subagent's output by running the appropriate §17 DoD gates:

   • Gate 1-3: lint, format, types (npm run lint, ruff check, mypy --strict)
   • Gate 4-5: unit tests + coverage (pytest --cov, vitest --coverage)
   • Gate 6: integration tests (requires compose services running)
   • Gate 7: security scan (bandit, npm audit --audit-level=high, gitleaks detect)
   • Gate 8-9: RBAC + tenant isolation (if auth/access changed)
   • Gate 10: AI eval suite (if workers/app/prompts/** or workers/app/ai/** changed)
   • Gate 11: migration roundtrip (if cms/migrations/** or infra/supabase/** changed)
   • Gate 12: docker compose build
   • Gate 13: playwright test (on final integration)

8. JUDGE: If all gates pass → go to step 9. If any gate fails → go to REPAIR.

9. REPAIR: Read the exact failure output. Generate a targeted fix prompt. Route back to the original subagent. Increment iteration counter. Return to step 7.

   • HALT if iteration >= 5 OR same gate fails with same root cause ≥ 3 times.
   • On halt: write BLOCKED-<T-NNNN>.md with full diagnosis and stop.

10. COMMIT:

    • Write conventional commit: feat(T-NNNN): <title>
    • Include evidence bundle in PR description: test output snippets, coverage report, eval results.

11. REPORT: Append to .claude/runs/<timestamp>/events.jsonl:

{"iteration": N, "subagent": "...", "action": "...", "gates_passed": [...], "gates_failed": [...], "retry_count": N}

12. Mark task as DONE in tasks/<T-NNNN>.md (check all acceptance criteria).