ralph-status

Ralph のステータス報告

概要

Ralph のステータスブロックは、自律ループの各反復の最後に含める、構造化された機械解析可能な進捗レポートです。自動モニタリング、終了検出、進捗追跡を可能にします。形式は厳密であり、正確に従う必要があります。機械解析では一貫した構造が必要です。

開始時に宣言：「この反復の RALPH_STATUS ブロックを生成します。」

トリガー条件

• 自律ループの各反復の終了時（必須）
• 自律ループで BUILD フェーズが完了した後
• モニタリングシステムで進捗データが必要な場合
• 終了ゲートの評価が必要な場合
• autonomous-loop スキルがこのスキルを呼び出した場合

---

フェーズ 1：データ収集

目標： ステータスブロックに必要なすべての指標を収集します。

1. この反復で完了したタスクの数を数えます
2. 変更したファイル（作成、編集、削除）の数を数えます
3. テストスイートを実行し、結果を記録します
4. 主な作業の種類を判断します
5. ブロッカーや問題がないか確認します

指標収集表

指標	判断方法	例
TASKS_COMPLETED_THIS_LOOP	この反復で完了としてマークされたタスクの数	1
FILES_MODIFIED	git diff または追跡情報で変更されたファイルの数	3
TESTS_STATUS	テストスイートを実行し、全体の結果を記録	PASSING
WORK_TYPE	主な作業を分類	IMPLEMENTATION
ブロッカー	進行できなかったタスクがあるか確認	なし

作業の種類の分類

作業の種類	使用する状況
IMPLEMENTATION	新しいコードを作成した（機能、エンドポイント、サービス）
TESTING	主な作業がテストの作成または修正だった
DOCUMENTATION	主な作業がドキュメント、仕様書、コメントだった
REFACTORING	動作を変更せずに主な作業として構造を変更した

停止 — 次の条件を満たすまでフェーズ 2 に進まないでください：

• すべての指標を収集済み
• テストスイートを実行済み（推測ではない）
• 作業の種類を判断済み

---

フェーズ 2：STATUS の評価

目標： 反復の結果に基づいて適切な STATUS 値を判断します。

STATUS の判断表

条件	STATUS 値	EXIT_SIGNAL
タスクが残っており、この反復で作業が完了した	IN_PROGRESS	false
タスクが残っており、作業は完了していない（調査中）	IN_PROGRESS	false
進行できず、外部からの入力が必要	BLOCKED	false
すべてのタスクが完了し、すべてのテストに合格	COMPLETE	フェーズ 3 で評価
すべてのタスクが完了したが、テストが失敗	IN_PROGRESS	false

STATUS 値の定義

値	意味	ループの動作
IN_PROGRESS	作業が進行中で、タスクが残っているかテストが失敗している	ループを続行
COMPLETE	計画された作業がすべて完了し、テストに合格	終了ゲートを評価
BLOCKED	外部からの入力なしでは進行できない	停止して報告

BLOCKED の場合

1. RECOMMENDATION に進行を妨げている要因を明確に記述します
2. EXIT_SIGNAL: false に設定します（BLOCKED は完了ではありません）
3. BLOCKED 状態が複数の反復にわたって続くと、サーキットブレーカーが作動する場合があります

停止 — 次の条件を満たすまでフェーズ 3 に進まないでください：

• STATUS 値を判断済み
• BLOCKED の場合、ブロッカーを明確に記述済み

---

フェーズ 3：EXIT_SIGNAL の評価

目標： EXIT_SIGNAL を true にするか false にするか判断します。

次の条件がすべて同時に満たされた場合に限り、EXIT_SIGNAL を `true` にできます：

条件	確認方法	必須
残りのタスクがない	IMPLEMENTATION_PLAN.md に未チェックの項目がない	はい
すべてのテストに合格	TESTS_STATUS が PASSING	はい
最新の反復でエラーがない	実行が正常に完了し、未解決の例外がない	はい
有意義な作業が残っていない	TODO、未完了の機能がなく、コードレビューが完了している	はい

EXIT_SIGNAL 判定表

残りのタスク	テストの状態	エラー	意味のある作業	EXIT_SIGNAL
あり	任意	任意	任意	false
なし	失敗	任意	任意	false
なし	成功	あり	任意	false
なし	成功	なし	あり	false
なし	成功	なし	なし	true

2 条件の終了ゲート

ループオーケストレーターは、終了を確認するために独立した 2 つのシグナルを使用します。

1. ヒューリスティック検出： 完了を示す表現（"all done"、"everything passes"、"no remaining work"）が直近の出力に 2 回以上含まれている
2. 明示的な宣言： ステータスブロックに EXIT_SIGNAL: true がある

両方が同時に満たされている必要があります。これにより、次の事態を防止できます。

• 何気ない完了表現による誤検出
• Claude が「完了」と言いながら生産的な作業を続けているときの早すぎる終了

停止してください。4 つの条件すべてを確認できない限り、EXIT_SIGNAL を true に設定してはいけません。

---

フェーズ 4：ブロックの出力

目標： 正確な形式で RALPH_STATUS ブロックを記述します。

ループの各反復は、必ずこの正確な形式で終了しなければなりません。形式の変更や追加フィールド、フィールドの欠落は認められません。

必須の形式

---RALPH_STATUS---
STATUS: [IN_PROGRESS | COMPLETE | BLOCKED]
TASKS_COMPLETED_THIS_LOOP: [number]
FILES_MODIFIED: [number]
TESTS_STATUS: [PASSING | FAILING | NOT_RUN]
WORK_TYPE: [IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING]
EXIT_SIGNAL: [false | true]
RECOMMENDATION: [one-line summary of next action or completion state]
---END_RALPH_STATUS---

フィールドの仕様

フィールド	型	許可される値	説明
STATUS	列挙型	IN_PROGRESS, COMPLETE, BLOCKED	現在の反復の結果
TASKS_COMPLETED_THIS_LOOP	整数	0 以上	この反復で完了したタスクの数
FILES_MODIFIED	整数	0 以上	変更（作成、編集、削除）したファイル数
TESTS_STATUS	列挙型	PASSING, FAILING, NOT_RUN	この反復後のテストスイートの状態
WORK_TYPE	列挙型	IMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORING	主な作業のカテゴリ
EXIT_SIGNAL	ブール値	false, true	すべての作業が完了しているかどうか
RECOMMENDATION	文字列	自由記述（1 行のみ）	次のアクションまたは最終的な要約

RECOMMENDATION のガイドライン

STATUS	RECOMMENDATION の内容
IN_PROGRESS	"次の作業：[具体的な次のタスク]"
COMPLETE	"すべてのタスクが完了し、テストも成功しました。[要約]"
BLOCKED	"ブロック中：[具体的な阻害要因の説明]"

---

フェーズ 5：検証

目標： 出力前にステータスブロックが正しいことを確認します。

検証項目

確認項目	ルール	違反時の対応
形式が正確	値を除き、テンプレートと一字一句一致する	ブロックを書き直す
STATUS の一貫性	COMPLETE の場合、EXIT_SIGNAL を評価する必要がある	STATUS または EXIT_SIGNAL を修正する
TESTS_STATUS が実際の状態と一致	値が実際のテスト実行結果と一致する	テストを再実行する
EXIT_SIGNAL に根拠がある	4 つの条件すべてを満たす場合にのみ true とする	false に設定する
RECOMMENDATION がある	空でなく、1 行である	推奨事項を追加する
余分なフィールドがない	定義済みの 7 つのフィールドのみ	余分なフィールドを削除する

---

アンチパターン／よくある間違い

アンチパターン	問題点	正しい方法
ステータスブロックを省略する	ループが終了を評価できず、監視もできない	各反復の最後にステータスを記述する
テストが失敗しているのに EXIT_SIGNAL を true に設定する	早すぎる終了、コードの不具合	4 つの条件すべてを確認する
独自のフィールドを追加する	機械による解析が失敗する	定義済みの 7 つのフィールドのみを使用する
複数行の RECOMMENDATION	改行によって解析が失敗する	1 行のみにする
テストを実行せずに TESTS_STATUS を記述する	誤った安心感を与える	実際にテストスイートを実行する
タスクが残っているのに STATUS を COMPLETE にする	シグナルに矛盾が生じる	IMPLEMENTATION_PLAN.md を確認する
RECOMMENDATION を省略する	次の反復への指針がない	常に実行可能な推奨事項を含める
BLOCKED のときに EXIT_SIGNAL を true にする	矛盾している。ブロック中は完了ではない	BLOCKED の場合は常に EXIT_SIGNAL: false とする
区切り文字の形式を変更する	機械による解析は正確な区切り文字に依存する	---RALPH_STATUS--- をそのまま使用する
FILES_MODIFIED を推測する	指標が不正確になる	実際の変更を数える

---

正当化を防ぐガード

ステータスブロックを省略してはいけません。4つの条件すべてを確認できない限り、EXIT_SIGNAL を true に設定してはいけません。ブロックの形式を変更してはいけません。機械による解析は、厳密で一貫した構造に依存しています。

次のように考えていることに気づいたら：

• 「ステータスブロックは単なる余計な手間……」— これは終了ゲートの仕組みです。絶対に省略しないでください。
• 「すべて完了したので、EXIT_SIGNAL: true……」— まず4つの条件すべてを確認してください。
• 「詳しい説明のためにフィールドを追加しよう……」— いいえ。詳細には RECOMMENDATION を使用してください。
• 「テストはおそらく通るので、TESTS_STATUS: PASSING……」— 実行してください。確認してください。その後で報告してください。

---

連携ポイント

スキル	関係	タイミング
autonomous-loop	親 — 各イテレーションの最後にこのスキルを呼び出します	毎イテレーション
circuit-breaker	利用側 — 停滞パターンを監視します	ステータスブロックを読み取ります
verification-before-completion	上流 — テスト結果を提供します	ステータスブロックの作成前
監視ダッシュボード	利用側 — 進捗をリアルタイムで表示します	ステータスブロックを読み取ります
ログ集約	利用側 — 過去のパフォーマンスを分析します	ステータスブロックを保存します

---

具体例

例：一般的な IN_PROGRESS ステータス

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 3
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Next: implement user authentication middleware
---END_RALPH_STATUS---

例：完了ステータス

---RALPH_STATUS---
STATUS: COMPLETE
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 2
TESTS_STATUS: PASSING
WORK_TYPE: DOCUMENTATION
EXIT_SIGNAL: true
RECOMMENDATION: All tasks complete, tests passing, documentation updated
---END_RALPH_STATUS---

例：ブロックされたステータス

---RALPH_STATUS---
STATUS: BLOCKED
TASKS_COMPLETED_THIS_LOOP: 0
FILES_MODIFIED: 0
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Blocked: need database credentials for integration test setup
---END_RALPH_STATUS---

例：テスト失敗ステータス

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 4
TESTS_STATUS: FAILING
WORK_TYPE: TESTING
EXIT_SIGNAL: false
RECOMMENDATION: 3 tests failing in auth module — investigating root cause next iteration
---END_RALPH_STATUS---

---

プロセスの概要

1. イテレーションの作業（実装、テスト、ドキュメント作成、リファクタリング）を完了します
2. 完了したタスク数と変更したファイル数を数えます
3. テストスイートを実行し、結果を記録します
4. STATUS の値を評価します
5. EXIT_SIGNAL の条件を評価します（true にするには4つすべてが真である必要があります）
6. RALPH_STATUS ブロックを厳密に指定された形式で記述します
7. 明確で実行可能な RECOMMENDATION を記載します

---

スキルの種類

RIGID — ステータスブロックの形式に厳密に従う必要があります。機械による解析は、一貫した構造に依存しています。フィールドの追加、形式の変更、ブロックの省略は禁止です。