| name | ralph-wiggum |
| description | Ralph-Wiggum ticket loop — auto-implement all ready tk tickets with worker + reviewer cycle |
Ralph-Wiggum Ticket Implementation Loop
The Ralph-Wiggum loop automatically implements tk tickets one by one until all are closed.
Each iteration: pick a ready ticket → implement → review → close (or retry with feedback).
Loop Protocol
Execute these steps in order. If any step fails, stop and report the error.
Step 1: Pick a ticket
tk ready
If the output is empty (no tickets): You are done. Do nothing — no file changes means the loop converges and stops.
If tickets are listed: Pick the first one. Extract the ticket ID (e.g., PR-xxxx).
Run tk start <TICKET_ID> to mark it in_progress.
Check how many times this ticket has been reviewed:
tk notes <TICKET_ID>
Count reviews (lines containing "Gate:"). If the ticket has been reviewed 3 or more times, it is stuck — skip it and move to the next ticket:
tk add-note <TICKET_ID> "BLOCKED: Escalated after 3 review cycles. Requires human intervention."
Step 2: Implement the ticket (Worker Subagent)
Read the ticket file and any prior notes first:
tk show <TICKET_ID>
tk notes <TICKET_ID>
Then delegate implementation to the worker agent using the subagent tool:
subagent({
agent: "worker",
task: "Implement ticket <TICKET_ID>. Read the ticket at .tickets/<TICKET_ID>.md for full requirements and acceptance criteria.\n\nPRIOR ATTEMPTS — read these notes from previous iterations carefully:\n<tk notes output>\n\nIf this is a retry (notes show prior failures), reflect on what went wrong before coding:\n- What specific issues did the reviewer flag?\n- What approach was tried?\n- What must be done differently this time?\nDo NOT repeat the same failing approach.\n\nAfter implementing:\n1. Run `ty check` to lint — fix any errors\n2. Run `mypy src/` for type checking — fix any errors\n3. Run `pytest tests/ -x -v` to test — fix failures until all tests pass\n4. Re-run linters after any fixes\n\nDo NOT close the ticket. Just implement and verify.",
context: "fresh"
})
Wait for the worker to complete. If the worker fails or crashes, retry once. If it fails again, add a note and move to the next ticket.
Step 3: Review the implementation (Reviewer Subagent)
Delegate the review to the rw-reviewer agent:
subagent({
agent: "rw-reviewer",
task: "Review the implementation of ticket <TICKET_ID>. The ticket file is at .tickets/<TICKET_ID>.md.\n\nVerify all acceptance criteria are met. Check code quality. Run git diff to see all changes.\n\nOutput your review in this exact format:\n\n## Gate: PASS | NITS | REVISE | ESCALATE\n\n### Findings\n\nFor each finding, use this format:\n- **[CRITICAL|HIGH|MEDIUM|LOW]** Title\n - File: <path>:<line>\n - Evidence: <concrete observation>\n - Remediation: <specific fix>\n\nIf Gate is PASS or NITS, briefly confirm acceptance criteria are met.\nIf Gate is REVISE, list only Critical and High findings.\nIf Gate is ESCALATE, explain why human intervention is needed.",
context: "fresh"
})
Step 4: Handle review result
Parse the reviewer's output for the Gate line. Record a structured note with iteration context:
If Gate: PASS or NITS:
tk add-note <TICKET_ID> "Review #<N>: Gate: PASS. <brief summary of what was implemented>"
tk close <TICKET_ID>
If Gate: REVISE:
tk add-note <TICKET_ID> "Review #<N>: Gate: REVISE. Issues to fix:\n\n<paste Critical and High findings with file refs and remediation>"
Keep the ticket in_progress. The next loop iteration will pick it up again.
If Gate: ESCALATE:
tk add-note <TICKET_ID> "Review #<N>: Gate: ESCALATE. Reason: <explanation>. Requires human intervention."
Move to the next ticket. Do not retry automatically.
Step 5: Done
Report what happened this iteration (ticket ID, gate result, key findings). The loop will continue automatically if there are more tickets.
Important Rules
- Always run
tk ready first — never assume which ticket to work on
- One ticket per iteration — the loop handles repetition
- Worker must pass lint + typecheck + tests before review
- Reviewer is read-only — it never modifies files
- Only close on PASS or NITS — REVISE means retry, ESCALATE means human needed
- Use
context: "fresh" for both subagents — they start clean
- If
tk ready is empty, do nothing — convergence stops the loop
- Max 3 review cycles per ticket — after that, escalate and skip
- Worker gets prior notes on retry — must reflect before re-attempting
- Reviewer output must be structured — severity, file, evidence, remediation
Gate Reference
| Gate | Meaning | Action |
|---|
| PASS | All acceptance criteria met, no issues | Close ticket |
| NITS | Acceptance criteria met, minor polish items | Close ticket (nits are optional) |
| REVISE | Critical or High issues found | Feed back to worker, retry |
| ESCALATE | Fundamentally blocked, needs human | Skip ticket, note why |
tk CLI Reference
| Command | Purpose |
|---|
tk ready | List tickets with all deps resolved (ready to work on) |
tk start <id> | Set ticket to in_progress |
tk close <id> | Set ticket to closed |
tk show <id> | Display ticket details |
tk notes <id> | Show ticket notes (prior iteration history) |
tk add-note <id> [text] | Append timestamped note |
tk blocked | List tickets with unresolved deps |
tk ls | List all open tickets |
tk dep tree <id> | Show dependency tree |