ratchet

Ratchet スキル

永続的なゲートを設けて、RPI ワークフローの進捗を追跡します。

注： /ratchet は進捗を追跡し、固定します。それ自体で「ループを実行」するわけではありません。実際に作業を実行するには、/crank（エピックループ）または /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. エージェントが ao ratchet status 2>/dev/null を呼び出して、現在の状態を確認します
2. CLI が .agents/ao/chain.jsonl を読み取り、進捗を解析します
3. エージェントが、完了・進行中・保留中のステップを報告します
4. エージェントが、完了したステップの出力成果物のパスを表示します
5. エージェントが、次に通過すべきゲートを特定します

結果： RPI ワークフローの進捗を一画面で確認でき、通過したゲートと次に行うことが表示されます。

ステップの完了を記録する

スキルの指示： /research の完了後

実行内容：

1. エージェントが ao ratchet record research --output ".agents/research/auth.md" を呼び出します
2. CLI が .agents/ao/chain.jsonl に完了エントリを追記します
3. エージェントが research ステップを完了済みとして永続的に固定します
4. エージェントが research ゲートの通過を確認したうえで、plan フェーズに進みます

結果： 進捗が永続的に記録され、ゲートが固定され、後戻りすることなくワークフローが進みます。

トラブルシューティング

問題	原因	解決策
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 — 実行可能な仕様：Chaos×Filter→Ratchet、ループステップのゲートを記録・確認する処理、単調増加するチェーン（soc-qk4b.2）