Ratchet Skill Track progress through the RPI workflow with permanent gates. Note: /ratchet tracks and locks progress. It does not “run the loop” by itself—pair it with /crank (epic loop) or /swarm (Ralph loop) to actually execute work. The Brownian Ratchet Progress = Chaos × Filter → Ratchet Phase What Happens Chaos Multiple attempts (exploration, implementation) Filter Validation gates (tests, /vibe, review) Ratchet Lock progress permanently (merged, closed, stored) Key insight: Progress is permanent. You can't un-ratchet. Execution Steps Given /ratchet [command] : status - Check Current State ao ratchet status 2
/dev/null Or check the chain manually: cat .agents/ao/chain.jsonl 2
/dev/null | tail -10 check [step] - Verify Gate ao ratchet check < step
2
/dev/null Steps: research , plan , implement , vibe , post-mortem record [step] - Record Completion ao ratchet record < step
--output "
" 2 /dev/null Or record manually by writing to chain: echo '{"step":"
","status":"completed","output":" ","time":" "}' .agents/ao/chain.jsonl skip [step] - Skip Intentionally ao ratchet skip < step
--reason "
" 2 /dev/null Workflow Steps Step Gate Output research Research artifact exists .agents/research/.md plan Plan artifact exists .agents/plans/.md implement Code + tests pass Source files vibe /vibe passes .agents/vibe/.md post-mortem Learnings extracted .agents/learnings/.md Chain Storage Progress stored in .agents/ao/chain.jsonl : { "step" : "research" , "status" : "completed" , "output" : ".agents/research/auth.md" , "time" : "2026-01-25T10:00:00Z" } { "step" : "plan" , "status" : "completed" , "output" : ".agents/plans/auth-plan.md" , "time" : "2026-01-25T11:00:00Z" } { "step" : "implement" , "status" : "in_progress" , "time" : "2026-01-25T12:00:00Z" } Key Rules Progress is permanent - can't un-ratchet Gates must pass - validate before proceeding Record everything - maintain the chain Skip explicitly - document why if skipping a step Examples Check RPI Progress User says: /ratchet status What happens: Agent calls ao ratchet status 2>/dev/null to check current state CLI reads .agents/ao/chain.jsonl and parses progress Agent reports which steps are completed, in-progress, or pending Agent shows output artifact paths for completed steps Agent identifies next gate to pass Result: Single-screen view of RPI workflow progress, showing which gates passed and what's next. Record Step Completion Skill says: After /research completes What happens: Agent calls ao ratchet record research --output ".agents/research/auth.md" CLI appends completion entry to .agents/ao/chain.jsonl Agent locks research step as permanently completed Agent proceeds to plan phase knowing research gate passed Result: Progress permanently recorded, gate locked, workflow advances without backsliding. Troubleshooting Problem Cause Solution ao ratchet status fails ao CLI not available or chain.jsonl missing Manually check .agents/ao/chain.jsonl or create empty file Step already completed error Attempting to re-ratchet locked step Use ao ratchet status to check state; skip if already done chain.jsonl corrupted Malformed JSON entries Manually edit to fix JSON; validate each line with jq -c '.'
Out-of-order steps Implementing before planning Follow RPI order strictly; use --skip only with explicit reason