ralph-status

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Status Reporting

Ralph 状态报告

Overview

概述

The Ralph status block is a structured, machine-parseable progress report included at the end of every autonomous loop iteration. It enables automated monitoring, exit detection, and progress tracking. The format is rigid and must be followed exactly — machine parsing depends on consistent structure.

Announce at start: "Producing RALPH_STATUS block for this iteration."

Ralph状态块是一种结构化、机器可解析的进度报告，会附加在每一次自主循环迭代的末尾。它支持自动化监控、退出检测和进度跟踪。其格式要求严格，必须完全遵守——机器解析依赖于一致的结构。

开头声明： "Producing RALPH_STATUS block for this iteration."

Trigger Conditions

触发条件

End of every autonomous loop iteration (mandatory)
After BUILD phase completes in the autonomous loop
When monitoring systems need progress data
When exit gate evaluation is needed
When the
```
autonomous-loop
```
skill invokes this skill

每一次自主循环迭代结束（强制要求）
自主循环的BUILD阶段完成后
监控系统需要进度数据时
需要进行退出门限评估时
当
```
autonomous-loop
```
技能调用本技能时

Phase 1: Data Collection

阶段1：数据收集

Goal: Gather all metrics needed for the status block.

Count tasks completed in this iteration
Count files modified (created, edited, deleted)
Run the test suite and record result
Determine the primary work type
Check for blockers or issues

目标： 收集状态块所需的所有指标。

统计本次迭代完成的任务数
统计修改的文件数（创建、编辑、删除）
运行测试套件并记录结果
确定核心工作类型
检查是否存在阻塞项或问题

Metric Collection Table

指标收集表

Metric	How to Determine	Example
TASKS_COMPLETED_THIS_LOOP	Count tasks marked complete this iteration	1
FILES_MODIFIED	Count files changed via git diff or tracking	3
TESTS_STATUS	Run test suite, record overall result	PASSING
WORK_TYPE	Categorize the primary activity	IMPLEMENTATION
Blockers	Check if any task was unable to proceed	None

Metric	判定方式	示例
TASKS_COMPLETED_THIS_LOOP	统计本次迭代中标记为完成的任务数	1
FILES_MODIFIED	通过git diff或追踪工具统计变更的文件数	3
TESTS_STATUS	运行测试套件，记录整体结果	PASSING
WORK_TYPE	对核心活动进行分类	IMPLEMENTATION
Blockers	检查是否有任务无法推进	None

Work Type Classification

工作类型分类

Work Type	When to Use
IMPLEMENTATION	New code written (features, endpoints, services)
TESTING	Primary activity was writing or fixing tests
DOCUMENTATION	Primary activity was docs, specs, or comments
REFACTORING	Primary activity was restructuring without behavior change

STOP — Do NOT proceed to Phase 2 until:

All metrics are collected
Test suite has been run (not assumed)
Work type is determined

工作类型	适用场景
IMPLEMENTATION	编写新代码（功能、接口、服务）
TESTING	核心活动为编写或修复测试用例
DOCUMENTATION	核心活动为编写文档、规范或注释
REFACTORING	核心活动为代码结构重构，不改变功能逻辑

停止 — 满足以下条件前请勿进入阶段2：

所有指标已收集完成
已实际运行测试套件（不得假设结果）
已确定工作类型

Phase 2: STATUS Evaluation

阶段2：STATUS 评估

Goal: Determine the correct STATUS value based on iteration outcome.

目标： 根据迭代结果确定正确的STATUS值。

STATUS Decision Table

STATUS 决策表

Condition	STATUS Value	EXIT_SIGNAL
Tasks remain, work completed this iteration	IN_PROGRESS	false
Tasks remain, no work completed (investigation)	IN_PROGRESS	false
Cannot proceed, needs external input	BLOCKED	false
All tasks complete, all tests pass	COMPLETE	Evaluate Phase 3
All tasks complete, tests failing	IN_PROGRESS	false

条件	STATUS 值	EXIT_SIGNAL
仍有未完成任务，本次迭代有产出	IN_PROGRESS	false
仍有未完成任务，本次迭代无产出（仅调研）	IN_PROGRESS	false
无法推进，需要外部输入	BLOCKED	false
所有任务完成，所有测试通过	COMPLETE	进入阶段3评估
所有任务完成，测试未通过	IN_PROGRESS	false

STATUS Values Defined

STATUS 值定义

Value	Meaning	Loop Action
IN_PROGRESS	Work is ongoing, tasks remain or tests failing	Continue loop
COMPLETE	All planned work is finished, tests pass	Evaluate exit gate
BLOCKED	Cannot proceed without external input	Halt and report

值	含义	循环动作
IN_PROGRESS	工作仍在进行，有未完成任务或测试未通过	继续循环
COMPLETE	所有计划工作已完成，测试通过	评估退出门限
BLOCKED	无外部输入则无法推进	暂停并上报

When BLOCKED

处于 BLOCKED 状态时

Clearly describe what is blocking progress in RECOMMENDATION
Set
```
EXIT_SIGNAL: false
```
(blocked is not complete)
The circuit breaker may activate if blocked state persists across iterations

STOP — Do NOT proceed to Phase 3 until:

STATUS value is determined
If BLOCKED, blocker is clearly described

在RECOMMENDATION中清晰描述阻塞进度的原因
设置
```
EXIT_SIGNAL: false
```
（阻塞不等于完成）
如果多次迭代都处于阻塞状态，熔断器可能会触发

停止 — 满足以下条件前请勿进入阶段3：

已确定STATUS值
如果为BLOCKED状态，已清晰描述阻塞原因

Phase 3: EXIT_SIGNAL Evaluation

阶段3：EXIT_SIGNAL 评估

Goal: Determine whether EXIT_SIGNAL should be true or false.

<HARD-GATE> EXIT_SIGNAL may ONLY be `true` when ALL of these conditions are simultaneously met: </HARD-GATE>

Condition	How to Verify	Required
No remaining tasks	IMPLEMENTATION_PLAN.md has no unchecked items	Yes
All tests pass	TESTS_STATUS is PASSING	Yes
No errors in latest iteration	Clean execution, no unresolved exceptions	Yes
No meaningful work remains	No TODOs, no incomplete features, code review done	Yes

目标： 确定EXIT_SIGNAL应该为true还是false。

<HARD-GATE> EXIT_SIGNAL仅当所有以下条件同时满足时才可以设为`true`： </HARD-GATE>

条件	校验方式	是否必填
无剩余任务	IMPLEMENTATION_PLAN.md中没有未勾选的项	是
所有测试通过	TESTS_STATUS为PASSING	是
本次迭代无错误	执行过程干净，无未解决的异常	是
无剩余有效工作	无TODO项、无未完成功能、代码评审已完成	是

EXIT_SIGNAL Decision Table

EXIT_SIGNAL 决策表

Tasks Remaining	Tests Status	Errors	Meaningful Work	EXIT_SIGNAL
Yes	Any	Any	Any	false
No	FAILING	Any	Any	false
No	PASSING	Yes	Any	false
No	PASSING	No	Yes	false
No	PASSING	No	No	true

剩余任务	测试状态	错误	剩余有效工作	EXIT_SIGNAL
是	任意	任意	任意	false
否	FAILING	任意	任意	false
否	PASSING	是	任意	false
否	PASSING	否	是	false
否	PASSING	否	否	true

Dual-Condition Exit Gate

双条件退出门限

The loop orchestrator uses TWO independent signals to confirm exit:

Heuristic detection: Completion language ("all done", "everything passes", "no remaining work") appears >= 2 times in recent output
Explicit declaration:
```
EXIT_SIGNAL: true
```
in the status block

Both must be true simultaneously. This prevents:

False positives from casual completion language
Premature exits when Claude says "done" while still working productively

STOP — Do NOT set EXIT_SIGNAL to true unless ALL four conditions are verified.

循环编排器需要两个独立信号同时满足才能确认退出：

启发式检测： 最近输出中出现完成类表述（"all done"、"everything passes"、"no remaining work"）的次数≥2次
显式声明： 状态块中
```
EXIT_SIGNAL: true
```

两个条件必须同时满足，避免以下问题：

随意的完成表述导致的误判
当Claude表示“已完成”但实际仍在有效工作时的提前退出

停止 — 除非所有四个条件都已校验通过，否则请勿将EXIT_SIGNAL设为true。

Phase 4: Block Production

阶段4：块生成

Goal: Write the RALPH_STATUS block in exact format.

<HARD-GATE> Every loop iteration MUST end with this exact format. No variations. No additional fields. No missing fields. </HARD-GATE>

目标： 严格按照格式编写RALPH_STATUS块。

<HARD-GATE> 每一次循环迭代必须严格遵循该格式结束。不得有任何变动、不得添加额外字段、不得缺失字段。 </HARD-GATE>

Required Format

要求格式

---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---

---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---

Field Specifications

字段规范

Field	Type	Allowed Values	Description
STATUS	enum	IN_PROGRESS, COMPLETE, BLOCKED	Current iteration outcome
TASKS_COMPLETED_THIS_LOOP	integer	0+	Number of tasks finished this iteration
FILES_MODIFIED	integer	0+	Number of files changed (created, edited, deleted)
TESTS_STATUS	enum	PASSING, FAILING, NOT_RUN	State of test suite after this iteration
WORK_TYPE	enum	IMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORING	Primary activity category
EXIT_SIGNAL	boolean	false, true	Whether all work is complete
RECOMMENDATION	string	Free text (one line only)	Next action or final summary

字段	类型	允许值	描述
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	字符串	自由文本（仅一行）	下一步动作或最终总结

RECOMMENDATION Guidelines

RECOMMENDATION 编写指南

STATUS	RECOMMENDATION Content
IN_PROGRESS	"Next: [specific next task]"
COMPLETE	"All tasks complete, tests passing, [summary]"
BLOCKED	"Blocked: [specific blocker description]"

STATUS	RECOMMENDATION 内容
IN_PROGRESS	"Next: [具体的下一个任务]"
COMPLETE	"All tasks complete, tests passing, [总结内容]"
BLOCKED	"Blocked: [具体的阻塞原因描述]"

Phase 5: Validation

阶段5：校验

Goal: Verify the status block is correct before output.

目标： 在输出前验证状态块是否正确。

Validation Checks

校验项

Check	Rule	If Violated
Format exact	Matches template character-for-character (except values)	Rewrite block
STATUS consistency	COMPLETE requires EXIT_SIGNAL evaluation	Fix STATUS or EXIT_SIGNAL
TESTS_STATUS matches reality	Value matches actual test run result	Re-run tests
EXIT_SIGNAL justified	true only when all 4 conditions met	Set to false
RECOMMENDATION present	Non-empty, one line	Add recommendation
No extra fields	Only the 7 defined fields	Remove extras

检查项	规则	违反后处理
格式完全匹配	除了填充值外，逐字符匹配模板	重写状态块
STATUS 一致性	COMPLETE状态必须完成EXIT_SIGNAL评估	修复STATUS或EXIT_SIGNAL
TESTS_STATUS 符合实际	值与实际测试运行结果一致	重新运行测试
EXIT_SIGNAL 合理	仅当所有4个条件满足时才能为true	设为false
RECOMMENDATION 存在	非空，仅一行	补充推荐内容
无额外字段	仅包含定义的7个字段	删除额外字段

Anti-Patterns / Common Mistakes

反模式/常见错误

Anti-Pattern	Why It Fails	Correct Approach
Omitting the status block	Loop cannot evaluate exit, monitoring blind	Every iteration ends with status
Setting EXIT_SIGNAL true with failing tests	Premature exit, broken code	Verify all 4 conditions
Adding custom fields	Machine parsing breaks	Only the 7 defined fields
Multi-line RECOMMENDATION	Parsing breaks on newlines	One line only
TESTS_STATUS without running tests	False confidence	Actually run the test suite
STATUS: COMPLETE with tasks remaining	Contradictory signal	Check IMPLEMENTATION_PLAN.md
Skipping RECOMMENDATION	No guidance for next iteration	Always include actionable recommendation
EXIT_SIGNAL: true when BLOCKED	Contradictory — blocked is not complete	BLOCKED always has EXIT_SIGNAL: false
Changing the;
Machine parsing depends on exact delimiters	Use ---RALPH_STATUS--- exactly
Guessing FILES_MODIFIED	Inaccurate metrics	Count actual changes

反模式	错误原因	正确做法
遗漏状态块	循环无法评估退出条件，监控失效	每次迭代末尾必须输出状态块
测试未通过时设置EXIT_SIGNAL为true	提前退出，提交有问题的代码	校验所有4个条件
添加自定义字段	破坏机器解析	仅使用定义的7个字段，额外信息放在RECOMMENDATION
多行RECOMMENDATION	换行导致解析失败	仅写一行
未运行测试就填写TESTS_STATUS	带来错误的信心	实际运行测试套件后再填写
仍有剩余任务时设置STATUS: COMPLETE	信号矛盾	检查IMPLEMENTATION_PLAN.md
跳过RECOMMENDATION	下一次迭代没有指导	始终包含可执行的推荐内容
BLOCKED状态时设置EXIT_SIGNAL: true	逻辑矛盾——阻塞不等于完成	BLOCKED状态的EXIT_SIGNAL永远为false
修改分隔符格式	机器解析依赖精确的分隔符	严格使用---RALPH_STATUS---格式
估算FILES_MODIFIED数值	指标不准确	统计实际变更的文件数

Anti-Rationalization Guards

反合理化防护

<HARD-GATE> Do NOT skip the status block. Do NOT set EXIT_SIGNAL to true unless all four conditions are verified. Do NOT modify the block; . Machine parsing depends on exact, consistent structure. </HARD-GATE>

If you catch yourself thinking:

"The status block is just overhead..." — It is the exit gate mechanism. Never skip.
"Everything is done, EXIT_SIGNAL: true..." — Verify ALL four conditions first.
"I'll add an extra field for more detail..." — No. Use RECOMMENDATION for details.
"Tests probably pass, TESTS_STATUS: PASSING..." — Run them. Verify. Then report.

<HARD-GATE> 不得跳过状态块生成。除非所有四个条件都校验通过，否则不得将EXIT_SIGNAL设为true。不得修改块格式。机器解析依赖于精确、一致的结构。 </HARD-GATE>

如果你出现以下想法：

"状态块只是多余的开销..." —— 它是退出门限机制，永远不能跳过。
"所有工作都做完了，直接设EXIT_SIGNAL: true..." —— 先校验所有四个条件。
"我加个额外字段说明更多细节..." —— 不行，额外信息放在RECOMMENDATION里。
"测试应该能过，直接填TESTS_STATUS: PASSING..." —— 实际运行，校验后再上报。

Integration Points

集成点

Skill	Relationship	When
`autonomous-loop`	Parent — invokes this skill at end of each iteration	Every iteration
`circuit-breaker`	Consumer — monitors for stagnation patterns	Reads status blocks
`verification-before-completion`	Upstream — provides test results	Before status block production
Monitoring dashboard	Consumer — displays real-time progress	Reads status blocks
Log aggregation	Consumer — historical performance analysis	Stores status blocks

技能	关系	触发时机
`autonomous-loop`	父技能——每次迭代结束时调用本技能	每次迭代
`circuit-breaker`	消费者——监控停滞模式	读取状态块
`verification-before-completion`	上游依赖——提供测试结果	生成状态块之前
监控面板	消费者——展示实时进度	读取状态块
日志聚合系统	消费者——历史性能分析	存储状态块

Concrete Examples

具体示例

Example: Typical IN_PROGRESS Status

示例：典型的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: 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---

Example: Completion 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: 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---

Example: Blocked 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: 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---

Example: Test Failure 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---

---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---

Process Summary

流程总结

Complete the iteration's work (implementation, testing, docs, or refactoring)
Count tasks completed and files modified
Run the test suite and record result
Evaluate STATUS value
Evaluate EXIT_SIGNAL conditions (all 4 must be true for
```
true
```
)
Write the RALPH_STATUS block in exact format
Include a clear, actionable RECOMMENDATION

完成本次迭代的工作（编码、测试、文档或重构）
统计完成的任务数和修改的文件数
运行测试套件并记录结果
评估STATUS值
评估EXIT_SIGNAL条件（4个条件全部满足才能设为
```
true
```
）
严格按照格式编写RALPH_STATUS块
包含清晰、可执行的RECOMMENDATION

Skill Type

技能类型

RIGID — The status block format must be followed exactly. Machine parsing depends on consistent structure. No field additions, no format changes, no skipped blocks.

RIGID — 必须严格遵守状态块格式。机器解析依赖于一致的结构。不得新增字段、不得修改格式、不得跳过块生成。