beo-reviewing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beo Reviewing

Beo 审查流程

Overview

概述

Reviewing is the post-execution quality gate. It verifies that the implementation actually delivers what

CONTEXT.md

specified, catches issues the workers missed, and formally closes the feature.

Core principle: Trust but verify. Workers may have drifted, cut corners, or missed edge cases.

Reviewing is for the final execution scope. If planning mode is

multi-phase

and later phases remain, route back to planning rather than reviewing the feature as if it were complete.

审查是执行后的质量门禁，用于验证实现代码是否切实交付了

CONTEXT.md

中约定的内容，排查执行环节遗漏的问题，并正式关闭功能开发流程。

核心原则：信任但要验证。执行方可能出现需求偏差、偷工减料或遗漏边界场景的情况。

审查仅针对最终执行范围。如果规划模式为

多阶段

且还有后续阶段未完成，应返回规划环节，而非将功能当作已完成状态进行审查。

Key Terms

关键术语

final execution scope: the last approved slice that should now be shippable and reviewable
P1: merge-blocking issue
P2: important follow-up that should not block closing the feature
P3: non-blocking improvement suggestion

最终执行范围：已获批的最后一段开发切片，当前应已具备可上线、可审查的条件
P1：阻断合并的问题
P2：重要后续优化项，不应阻断功能关闭流程
P3：非阻断性改进建议

Default Review Loop

默认审查循环

confirm the final execution scope is actually complete
run specialist review
verify promised artifacts are real and wired
walk the user through decisions and exit-state claims one at a time
route any changes back through execution or planning as needed
finish only after P1 issues are resolved and human UAT is complete

Load

references/reviewing-operations.md

for the exact specialist prompts, finishing steps, and checkpoint mechanics.

确认最终执行范围已实际完成
开展专家审查
验证约定的交付制品真实存在且已正确接入
逐一向用户同步决策内容和退出状态声明
如有变更需求，根据情况返回执行或规划环节
仅当P1问题全部解决、人工UAT完成后才可结束审查

如需获取准确的专家提示词、结束步骤和检查点机制，请加载

references/reviewing-operations.md

。

Prerequisites

前置条件

Default checks:

bash

br dep list <EPIC_ID> --direction up --type parent-child --json
cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null
cat .beads/artifacts/<feature-name>/approach.md 2>/dev/null
cat .beads/artifacts/<feature-name>/phase-plan.md 2>/dev/null
cat .beads/artifacts/<feature-name>/phase-contract.md 2>/dev/null
cat .beads/artifacts/<feature-name>/story-map.md 2>/dev/null

Load

references/reviewing-operations.md

for the exact prerequisite checks, isolated review inputs, and finishing prerequisites.

<HARD-GATE> If tasks from the final execution scope are still open or in progress, route back to `beo-executing`. If any tasks have `blocked`, `failed`, or `partial` labels (status `deferred`), stop and get explicit user direction to proceed, defer, or re-plan before closing the epic. If `planning_mode = multi-phase` and later phases remain, do not treat the feature as complete; route back to `beo-planning`. </HARD-GATE>

默认检查项：

bash

br dep list <EPIC_ID> --direction up --type parent-child --json
cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null
cat .beads/artifacts/<feature-name>/approach.md 2>/dev/null
cat .beads/artifacts/<feature-name>/phase-plan.md 2>/dev/null
cat .beads/artifacts/<feature-name>/phase-contract.md 2>/dev/null
cat .beads/artifacts/<feature-name>/story-map.md 2>/dev/null

如需获取准确的前置条件检查、隔离审查输入和完成前置要求，请加载

references/reviewing-operations.md

。

<硬门禁> 如果最终执行范围内的任务仍处于未完成或进行中状态，返回

beo-executing

环节。如果任何任务带有

blocked

、

failed

或

partial

标签（状态为

deferred

），停止流程并明确征求用户指示，确认是继续推进、延期还是重新规划后再关闭史诗。如果

planning_mode = multi-phase

且仍有后续阶段未完成，不得将功能视为已完成，返回

beo-planning

环节。 </硬门禁>

Phase 1: Automated Review

阶段1：自动化审查

Launch specialist review subagents to examine the implementation from different angles.

Load

references/review-specialist-prompts.md

for the full specialist table, prompt template, dispatch strategy, and P1/P2/P3 bead creation patterns.

Summary: 5 specialists (Code Quality, Architecture, Security, Test Coverage, Learnings Synthesis) review changed files. Launch first 4 in parallel, learnings synthesizer last. Each reports findings as P1 (blocks merge), P2 (should fix), or P3 (nice to have).

P1 findings become fix beads under the epic, executed immediately, using the shared Reactive Fix Bead Template
P2 findings become independent follow-up beads (NOT under epic), using the shared Follow-Up Bead Template
P3 findings recorded but no beads unless user requests
If P1 fixes fail >2 attempts, route to
```
beo-debugging
```

Use isolated review context whenever possible: changed files / diff,

CONTEXT.md

approach.md

, and final current-phase artifacts.

启动专家审查子Agent，从不同维度检查实现代码。

如需获取完整的专家信息表、提示词模板、分发策略和P1/P2/P3 bead创建规则，请加载

references/review-specialist-prompts.md

。

概要：5名专家（代码质量、架构、安全、测试覆盖、经验总结）审查变更文件。前4名专家并行启动，最后启动经验总结专家。每个专家的发现分为P1（阻断合并）、P2（应修复）、P3（建议优化）三个等级。

P1问题会作为修复bead归入当前史诗下，使用通用的响应式修复Bead模板立即执行
P2问题会作为独立的后续优化bead（不归入当前史诗），使用通用的后续优化Bead模板创建
P3问题仅做记录，除非用户要求否则不创建bead
如果P1修复尝试失败超过2次，转入
```
beo-debugging
```
环节

尽可能使用隔离的审查上下文：变更文件/差异、

CONTEXT.md

、

approach.md

和当前阶段的最终制品。

Severity Examples

严重等级示例

P1: security hole, broken acceptance path, data-loss risk, or a locked decision from
```
CONTEXT.md
```
is not actually met
P2: maintainability problem, weak edge-case handling, incomplete tests, or a risky design choice that should be corrected soon
P3: polish, naming, cleanup, readability, or a non-blocking improvement suggestion

When unsure between P1 and P2, ask: "Would I block merge if this remained unfixed?" If yes, it is P1.

P1：安全漏洞、验收路径失效、数据丢失风险，或未满足
```
CONTEXT.md
```
中锁定的决策要求
P2：可维护性问题、边界场景处理不足、测试不完整，或需要尽快修正的高风险设计选择
P3：体验优化、命名规范、清理冗余、可读性优化，或非阻断性改进建议

如果无法判断是P1还是P2，自问：「如果这个问题不修复，我会阻断合并吗？」如果答案是肯定的，则为P1。

Phase 2: Artifact Verification

阶段2：制品验证

Verify that all implementation artifacts promised by the final execution scope are real, substantive, and wired.

Default artifact-verification questions:

does the artifact exist?
is it substantive rather than placeholder content?
is it wired into the actual feature path?

Load

references/reviewing-operations.md

for the 3-level verification procedure, command shapes, and finishing flow.

验证最终执行范围承诺的所有实现制品真实存在、内容有效且已正确接入。

默认制品验证问题：

制品是否存在？
内容是否真实有效，而非占位内容？
是否已正确接入实际功能路径？

如需获取三级验证流程、命令结构和完成流程，请加载

references/reviewing-operations.md

。

Phase 3: Human UAT

阶段3：人工UAT

<HARD-GATE> Human review is required. Use the canonical rule from `../reference/references/approval-gates.md` and walk through the feature with the user. </HARD-GATE>

<硬门禁> 必须进行人工审查。遵循

../reference/references/approval-gates.md

中的通用规则，与用户逐一核对功能。 </硬门禁>

UAT Protocol

UAT流程

For each locked decision from

CONTEXT.md

(D1, D2, ...):

State the decision
Show how the implementation fulfills it
Ask: "Does this match your intent?"

Walk through ONE decision at a time. Wait for user confirmation before moving to the next.

Additionally, verify against the relevant exit state from

phase-contract.md

For each exit-state line:

State the exit-state claim
Show how the implementation satisfies it
Ask: "Is this exit state now true?"

针对

CONTEXT.md

中的每个锁定决策（D1、D2……）：

说明决策内容
展示实现代码如何满足该决策
询问：「这是否符合你的预期？」

每次仅核对一个决策，等待用户确认后再进入下一个。

此外，对照

phase-contract.md

中的相关退出状态进行验证：

针对每一条退出状态：

说明退出状态声明
展示实现代码如何满足该状态
询问：「当前是否已满足该退出状态？」

UAT Outcomes

UAT结果处理

Load

references/reviewing-operations.md

for the canonical UAT outcome handling.

如需获取通用的UAT结果处理规则，请加载

references/reviewing-operations.md

。

Scope Change During UAT

UAT期间的范围变更

If the user changes a decision:

Update
```
CONTEXT.md
```
with the new decision
Assess which tasks are affected
If minor (1-2 files) → create fix bead, execute
If major (architectural change or changes to feature sequencing) → stop reviewing, strip
```
approved
```
label (
```
br label remove <EPIC_ID> -l approved
```
), route to
```
beo-planning
```

如果用户修改了决策：

更新
```
CONTEXT.md
```
中的决策内容
评估受影响的任务
如果是 minor 变更（1-2个文件）→ 创建修复bead并执行
如果是 major 变更（架构调整或功能顺序变更）→ 停止审查，移除
```
approved
```
标签（
```
br label remove <EPIC_ID> -l approved
```
），转入
```
beo-planning
```
环节

Phase 4: Finishing

阶段4：收尾

After all P1 issues are resolved, artifacts are verified, and UAT is complete, load

references/reviewing-operations.md

for the exact finishing sequence, review-findings handoff, merge-path presentation, optional AGENTS.md sync, and cleanup rule.

所有P1问题解决、制品验证通过、UAT完成后，加载

references/reviewing-operations.md

获取准确的收尾顺序、审查结果交接、合并路径展示、可选的AGENTS.md同步和清理规则。

Completion

完成

Announce:

text

Feature "<feature-name>" is complete.

Review Summary:
- Specialist reviews: <N> findings (<P1 count> P1, <P2 count> P2, <P3 count> P3)
- P1 fixes: <N> resolved
- P2 follow-ups: <N> beads created
- Artifact verification: <N>/<total> L3 verified
- UAT: <N>/<total> decisions confirmed

Epic <EPIC_ID> is closed.
Review findings saved for compounding.

Next: Load beo-compounding to capture learnings and promote critical patterns.

发布通知：

text

Feature "<feature-name>" is complete.

Review Summary:
- Specialist reviews: <N> findings (<P1 count> P1, <P2 count> P2, <P3 count> P3)
- P1 fixes: <N> resolved
- P2 follow-ups: <N> beads created
- Artifact verification: <N>/<total> L3 verified
- UAT: <N>/<total> decisions confirmed

Epic <EPIC_ID> is closed.
Review findings saved for compounding.

Next: Load beo-compounding to capture learnings and promote critical patterns.

Lightweight Mode

轻量模式

Load

references/reviewing-operations.md

for the lightweight-review shortcut.

如需获取轻量审查快捷方式，请加载

references/reviewing-operations.md

。

Context Budget

上下文预算

If context usage exceeds 65%, use

references/reviewing-operations.md

together with

../reference/references/state-and-handoff-protocol.md

for the canonical checkpoint behavior.

如果上下文使用率超过65%，结合

references/reviewing-operations.md

和

../reference/references/state-and-handoff-protocol.md

中的通用检查点规则处理。

Red Flags

危险信号

Flag	Description
Skipping specialist reviews	"The code looks fine" is not a review
Auto-passing UAT	User must confirm each decision
Ignoring P1 findings	P1 blocks merge; no exceptions
Closing epic with open P1 fixes	All P1 beads must be closed first
Promoting learnings without approval	critical-patterns.md is shared; ask first
Skipping build/test/lint	Full build/test/lint verification is mandatory before closing the epic
Reviewing before later phases are planned/executed	Multi-phase feature is not done just because the current phase is done

信号	描述
跳过专家审查	「代码看起来没问题」不等于完成审查
自动通过UAT	用户必须确认每一项决策
忽略P1问题	P1问题阻断合并，无例外
还有未解决的P1修复就关闭史诗	必须先关闭所有P1 bead
未经批准就推广经验	critical-patterns.md是共享文件，需先征求同意
跳过构建/测试/语法检查	关闭史诗前必须完成完整的构建/测试/语法检查验证
后续阶段还未规划/执行就开展审查	多阶段功能不会因为当前阶段完成就整体完工

Anti-Patterns

反模式

Pattern	Why It's Wrong	Instead
Reviewing your own code (same agent that implemented)	Blind spots	Use fresh subagents with isolated context
Creating P1 beads under a different epic	Breaks the dependency chain	P1 beads go under the current epic
Creating P2/P3 beads under the current epic	Blocks feature completion	P2/P3 are independent follow-up beads
Closing the epic before UAT	User hasn't confirmed	Always complete Phase 3 first
Skipping learnings capture	Wastes institutional memory	At minimum, run the learnings synthesizer
Writing novel code during review	That's execution, not review	Create beads for any needed changes

模式	问题	正确做法
审查自己编写的代码（实现功能的同一个Agent）	存在盲区	使用带有隔离上下文的全新子Agent
在其他史诗下创建P1 bead	破坏依赖链	P1 bead归入当前史诗
在当前史诗下创建P2/P3 bead	阻断功能完成流程	P2/P3作为独立的后续优化bead
UAT完成前关闭史诗	还未获得用户确认	始终先完成阶段3
跳过经验总结	浪费团队经验沉淀	至少要运行经验总结Agent
审查期间编写新代码	属于执行环节而非审查	为所有需要的变更创建bead