ratchet

Ratchet 技能

通过永久门禁跟踪 RPI 工作流进度。

注意：/ratchet 用于跟踪并锁定进度。它本身不会“运行循环”——搭配 /crank（Epic 循环）或 /swarm（Ralph 循环）才能实际执行工作。

布朗棘轮

Progress = Chaos × Filter → Ratchet

阶段	发生的事情
混沌	多次尝试（探索、实现）
筛选	验证门禁（测试、/vibe、审查）
棘轮	永久锁定进度（合并、关闭、存储）

**关键要点：**进度是永久的。棘轮无法回退。

执行步骤

对于 /ratchet [command]：

status - 检查当前状态

ao ratchet status 2>/dev/null

或者手动检查链：

cat .agents/ao/chain.jsonl 2>/dev/null | tail -10

check [step] - 验证门禁

ao ratchet check <step> 2>/dev/null

步骤：research、plan、implement、vibe、post-mortem

record [step] - 记录完成情况

ao ratchet record <step> --output "<artifact-path>" 2>/dev/null

或者手动写入链来记录：

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

skip [step] - 有意跳过

ao ratchet skip <step> --reason "<why>" 2>/dev/null

工作流步骤

步骤	门禁	输出
research	研究文档已存在	.agents/research/*.md
plan	计划文档已存在	.agents/plans/*.md
implement	代码和测试通过	源文件
vibe	/vibe 通过	.agents/vibe/*.md
post-mortem	已提取经验	.agents/learnings/*.md

链存储

进度存储在 .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"}

关键规则

• 进度是永久的——无法回退棘轮
• 门禁必须通过——继续之前先验证
• 记录一切——维护链
• 明确跳过——跳过步骤时说明原因

示例

检查 RPI 进度

用户说：/ratchet status

发生的事情：

1. Agent 调用 ao ratchet status 2>/dev/null 检查当前状态
2. CLI 读取 .agents/ao/chain.jsonl 并解析进度
3. Agent 报告已完成、进行中或待处理的步骤
4. Agent 显示已完成步骤的输出文档路径
5. Agent 指出下一个需要通过的门禁

**结果：**在单个屏幕中查看 RPI 工作流进度，了解已通过的门禁和后续步骤。

记录步骤完成情况

技能说明：/research 完成后

发生的事情：

1. Agent 调用 ao ratchet record research --output ".agents/research/auth.md"
2. CLI 将完成记录追加到 .agents/ao/chain.jsonl
3. Agent 将 research 步骤永久锁定为已完成
4. Agent 在确认 research 门禁已通过后进入计划阶段

**结果：**进度永久记录，门禁锁定，工作流向前推进且不会倒退。

故障排除

问题	原因	解决方案
ao ratchet status 失败	ao CLI 不可用，或 chain.jsonl 缺失	手动检查 .agents/ao/chain.jsonl，或创建空文件
步骤已完成错误	尝试再次棘轮已锁定的步骤	使用 ao ratchet status 检查状态；如果已完成则跳过
chain.jsonl 已损坏	JSON 条目格式错误	手动编辑以修复 JSON；使用 jq -c '.' <file> 验证每一行
步骤顺序错误	尚未规划就开始实现	严格遵循 RPI 顺序；仅在明确说明原因时使用 --skip

参考文档

• references/ratchet.feature — 可执行规范：混沌×筛选→棘轮、记录/检查循环步骤门禁、单调递增的链（soc-qk4b.2）