ratchet

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

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

Steps: research, plan, implement, vibe, post-mortem

record [step] - Record Completion

Or record manually by writing to chain:

skip [step] - Skip Intentionally

Workflow Steps

Chain Storage

Progress stored in .agents/ao/chain.jsonl:

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:

1. Agent calls ao ratchet status 2>/dev/null to check current state
2. CLI reads .agents/ao/chain.jsonl and parses progress
3. Agent reports which steps are completed, in-progress, or pending
4. Agent shows output artifact paths for completed steps
5. 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:

1. Agent calls ao ratchet record research --output ".agents/research/auth.md"
2. CLI appends completion entry to .agents/ao/chain.jsonl
3. Agent locks research step as permanently completed
4. Agent proceeds to plan phase knowing research gate passed

Result: Progress permanently recorded, gate locked, workflow advances without backsliding.

Troubleshooting

Reference Documents

• references/ratchet.feature [blocked] — Executable spec: Chaos×Filter→Ratchet, record/check loop-step gates, monotonic chain (soc-qk4b.2)