ralph-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

STARTER_CHARACTER = 🔍

STARTER_CHARACTER = 🔍

Ralph Review

Ralph 审核

Dispatch a subagent to review the ralph plan and bd graph for defects.

调度一个子代理来审核ralph计划和bd图中的缺陷。

Dispatch

调度

The launcher validates the bd graph, captures graph state, then invokes the subagent.

启动器会验证bd图，捕获图状态，然后调用子代理。

1. Validate the bd Graph

1. 验证bd图

Derive the slug and locate the run epic:

bash

PROJECT_ROOT=$(git rev-parse --show-toplevel)
SLUG=$(git branch --show-current | tr '/' '-')
EPIC=$(bd list -t epic -l "ralph:${SLUG}" --json | jq -r '[.[] | select(.status=="open")] | .[0].id // empty')

Run structural checks. Each failure is a HIGH finding:

Exactly one open epic with label
```
ralph:${SLUG}
```
```
bd dep cycles
```
reports no cycles
Epic has at least one child (
```
bd list --parent "$EPIC"
```
)
At least one ready task (
```
bd ready --parent "$EPIC"
```
)
Every child has a description

Parent set (

bd list --parent "$EPIC"

) equals label set (

bd list --label "ralph:${SLUG}"

excluding the epic)

Check for isolated nodes (MEDIUM).

If any HIGH finding, report directly and stop. The graph must be sound before review.

获取slug并定位运行epic：

bash

PROJECT_ROOT=$(git rev-parse --show-toplevel)
SLUG=$(git branch --show-current | tr '/' '-')
EPIC=$(bd list -t epic -l "ralph:${SLUG}" --json | jq -r '[.[] | select(.status=="open")] | .[0].id // empty')

运行结构检查。每一项失败都属于高优先级（HIGH）问题：

恰好有一个带有
```
ralph:${SLUG}
```
标签的开放epic
```
bd dep cycles
```
报告无循环
Epic至少有一个子任务（
```
bd list --parent "$EPIC"
```
）
至少有一个就绪任务（
```
bd ready --parent "$EPIC"
```
）
每个子任务都有描述
父任务集合（
```
bd list --parent "$EPIC"
```
）等于标签集合（排除epic的
```
bd list --label "ralph:${SLUG}"
```
）

检查孤立节点（中优先级MEDIUM）。

如果存在任何高优先级问题，直接报告并停止。审核前必须确保图是合理的。

2. Capture Graph State

2. 捕获图状态

bash

bd list --parent "$EPIC" --json
bd ready --parent "$EPIC" --json
bd list --label "ralph:${SLUG}" --json

bash

bd list --parent "$EPIC" --json
bd ready --parent "$EPIC" --json
bd list --label "ralph:${SLUG}" --json

3. Invoke the Subagent

3. 调用子代理

Dispatch a subagent with the review prompt below. Substitute

<PROJECT_ROOT>

<SLUG>

<EPIC>

, the graph validation findings, and the captured graph state.

Relay the response verbatim, prefixed with the graph validation findings.

使用以下审核提示调度子代理。替换

<PROJECT_ROOT>

、

<SLUG>

、

<EPIC>

、图验证结果以及捕获的图状态。

直接转发响应，前缀加上图验证结果。

Review Prompt

审核提示

You are a plan reviewer. Read the plan, evaluate it against the graph state, and review for defects.

你是一名计划审核员。阅读计划，对照图状态进行评估，并审核其中的缺陷。

Source

来源

Read

<PROJECT_ROOT>/.llmtmp/ralph-plan.md

. Then locate the

## Inputs

section and parse the

plan documents:

line. Split on commas, trim whitespace, Read each path. These are plan documents: forward-looking intent the planner consulted (a PRD, a design note). The plan must faithfully render them. Flag the plan if it omits, contradicts, or stale-references a plan document requirement.

读取

<PROJECT_ROOT>/.llmtmp/ralph-plan.md

。然后找到

## Inputs

部分并解析

plan documents:

行。按逗号拆分，去除空格，读取每个路径。这些是计划文档：规划者参考的前瞻性意图文档（如PRD、设计说明）。计划必须忠实地体现这些文档的内容。如果计划遗漏、矛盾或过时引用了计划文档中的要求，请标记该计划。

How Ralph Loops Work

Ralph循环的工作原理

A ralph loop is an autonomous, iterative execution mechanism. Two modes share the same artifacts:

In-session (ralph-loop plugin): a Stop hook re-feeds the prompt to the same Claude session.
External (scripts/ralph.sh): a bash while-loop spawns a fresh
```
claude --print
```
per iteration.

Mechanics:

The bd graph is the state machine. Each run is organized under a per-run epic; concurrent worktrees stay isolated by
```
--parent
```
filtering.
The run epic carries label
```
ralph:<slug>
```
. Every child task carries both
```
--parent <epic>
```
and the same label. The two signals are independent for orphan detection.
The plan's "Run Identity" section records the literal slug and epic ID. The agent reads them from the plan each iteration.
One task per iteration. The agent reads
```
bd ready --parent <epic> --json
```
, takes the first result, executes its description, closes the task, then stops.
When the ready queue is empty, the agent closes the epic and emits the sentinel.
Every action is a bd task (branch creation, BEGIN tag, code, docs, END tag), all parented to the run epic.
Each bead carries full instructions in its description: files, verification command, commit message.
Run-wide conventions live in ralph-plan.md, not in every description.
Environment is a precondition. Credentials, toolchain, and runtime dependencies are the operator's responsibility.

Accepted patterns (do not flag): collapsing tasks into bundles, partial completion, the

ralph:<slug>

label as run-identity (not workflow dispatch).

Ralph循环是一种自主的迭代执行机制。两种模式共享相同的工件：

会话内（ralph-loop插件）：Stop钩子会将提示重新反馈到同一个Claude会话中。
外部模式（scripts/ralph.sh）：bash while循环会在每次迭代时生成一个新的
```
claude --print
```
进程。

机制：

bd图是状态机。每次运行都组织在一个按运行划分的epic下；并发工作树通过
```
--parent
```
过滤保持隔离。
运行epic带有
```
ralph:<slug>
```
标签。每个子任务同时带有
```
--parent <epic>
```
和相同的标签。这两个信号独立用于检测孤立任务。
计划的“Run Identity”部分记录了实际的slug和epic ID。代理每次迭代都会从计划中读取这些信息。
每次迭代处理一个任务。代理读取
```
bd ready --parent <epic> --json
```
，获取第一个结果，执行其描述，关闭任务，然后停止。
当就绪队列为空时，代理关闭epic并发出标记信号。
每个操作都是一个bd任务（分支创建、BEGIN标签、代码、文档、END标签），均归属于运行epic。
每个任务的描述中包含完整指令：文件、验证命令、提交信息。
运行范围的约定在ralph-plan.md中，而非每个任务描述中。
环境是前提条件。凭证、工具链和运行时依赖由操作者负责。

可接受的模式（无需标记）：将任务合并为bundle、部分完成、使用

ralph:<slug>

标签作为运行标识（而非工作流调度）。

What Counts as a Finding

什么属于问题

A finding is a defect, gap, or risk the author should fix before execution. Conformance is the baseline, not a finding. Severity is HIGH or MEDIUM only. Omit anything less severe.

HIGH: zero or multiple open epics for

ralph:<slug>

; empty descriptions; graph cycles; no children under epic; children but no ready tasks; parent/label set mismatch; per-task workflow continues after

bd close

instead of stopping; per-task workflow omits epic closure before sentinel; missing Run Identity section; missing Inputs section with

plan documents:

line; plan contradicts a plan document; Approach prose declares ordering the dependency edges do not enforce.

MEDIUM: description omits verification command or commit message; isolated task in a multi-task graph; plan duplicates bead descriptions; bead touching README.md/CLAUDE.md/.llmdocs/ authors edits instead of running the docs skill (/docs, $docs).

问题指的是作者在执行前需要修复的缺陷、缺口或风险。合规性是基线，不属于问题。严重程度仅分为高优先级（HIGH）或中优先级（MEDIUM）。忽略严重程度更低的内容。

高优先级：

ralph:<slug>

对应的开放epic为0个或多个；描述为空；图存在循环；epic下无子任务；有子任务但无就绪任务；父任务/标签集合不匹配；

bd close

后仍继续执行单任务工作流；发出标记信号前未关闭epic；缺少Run Identity部分；缺少包含

plan documents:

行的Inputs部分；计划与计划文档矛盾；方法说明中声明的顺序未被依赖边强制执行。

中优先级：描述遗漏验证命令或提交信息；多任务图中的孤立任务；计划重复任务描述；任务直接修改README.md/CLAUDE.md/.llmdocs/作者编辑内容，而非调用docs技能（/docs, $docs）。

Evaluation Areas

评估领域

Review for these defect patterns only. Report defects found, nothing else.

Goal Clarity - vague objective; fresh-context iteration cannot determine success from the plan alone
Task Decomposition - wrong granularity; tasks not independently completable; missing or redundant tasks; technique-named titles; insufficient description detail for cold-start worker
Sequencing and Dependencies - incorrect edges;
```
bd ready
```
order produces wrong results; implicit dependencies missing explicit edges; cycles; isolated nodes
Plan Completeness - missing conventions/tools/commands; inaccurate build/test/lint commands; unclear per-task workflow; missing Run Identity; missing epic scoping in workflow; missing epic closure; missing STOP instruction; missing
```
ralph/
```
branch and BEGIN/END tags; inline edits instead of docs skill delegation
Risk and Gaps - autonomous execution failures; tasks requiring human judgment; tasks that leave repo broken
Feasibility - tasks a single iteration cannot realistically complete; tasks exceeding fresh-context autonomy

仅针对这些缺陷模式进行审核。仅报告发现的缺陷，不涉及其他内容。

目标清晰度 - 目标模糊；仅通过计划无法让新上下文迭代确定成功标准
任务分解 - 粒度不当；任务无法独立完成；任务缺失或冗余；标题以技术命名；冷启动执行者无法获得足够的描述细节
排序与依赖 - 边设置错误；
```
bd ready
```
顺序导致错误结果；隐式依赖缺少显式边；循环；孤立节点
计划完整性 - 缺少约定/工具/命令；构建/测试/ lint命令不准确；单任务工作流不清晰；缺少Run Identity；工作流中缺少epic范围界定；缺少epic关闭步骤；缺少STOP指令；缺少
```
ralph/
```
分支和BEGIN/END标签；直接编辑而非委托给docs技能
风险与缺口 - 自主执行失败；需要人工判断的任务；会导致仓库损坏的任务
可行性 - 单次迭代无法实际完成的任务；超出新上下文自主能力的任务

Output Format

输出格式

text

undefined

text

undefined

Ralph Loop Review

Goal Clarity

Task Decomposition

Sequencing and Dependencies

Plan Completeness

Risk and Gaps

Feasibility

Summary


Finding format: `- **[high]** Title. Description.` or `- **[medium]** Title. Description.`

Every section heading present. Defects only under each. 'No findings.' when a section has no defects.

Summary: overall assessment and top 3 recommendations.

Cite task IDs and section names. Produce the review, nothing else.


问题格式：`- **[high]** 标题。描述。` 或 `- **[medium]** 标题。描述。`

保留所有章节标题。每个章节下仅列出缺陷。如果章节没有缺陷，标注“无问题。”

摘要：整体评估和前3项建议。

引用任务ID和章节名称。仅生成审核内容，无需其他内容。