majiayu000 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/nullto check current state - CLI reads
.agents/ao/chain.jsonland 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 |
Reference Documents
- references/ratchet.feature — Executable spec: Chaos×Filter→Ratchet, record/check loop-step gates, monotonic chain (soc-qk4b.2)