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 "<artifact-path>" 2>/dev/null

Or record manually by writing to chain:

echo '{"step":"<step>","status":"completed","output":"<path>","time":"<ISO-timestamp>"}' >> .agents/ao/chain.jsonl

skip [step] - Skip Intentionally

ao ratchet skip <step> --reason "<why>" 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 '.' <file>

Out-of-order steps

Implementing before planning

Follow RPI order strictly; use --skip only with explicit reason