beo-validating

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beo Validating

Beo 验证

Overview

概述

Validating is the critical gate between planning and execution. No code is written until this skill completes successfully.

Core principle: Catch plan failures before they become implementation failures.

This skill treats the current phase as a small closed loop -- clear entry state, clear exit state, simple demo story, stories that explain the internal order, and beads that implement those stories. The 8-dimension check (Phase 1) verifies this loop is sound.

phase-plan.md

exists, validating still focuses on the current phase only. Whole-feature sequencing informs the validator, but current-phase approval does not approve later phases.

验证是规划与执行之间的关键关口。在该技能执行通过前，不允许编写任何代码。

核心原则：在计划缺陷演变为实现缺陷前提前发现。

该技能将当前阶段视作一个小型闭环——有明确的进入状态、退出状态、简单的演示故事、说明内部顺序的故事，以及实现这些故事的bead。8维度检查（第一阶段）会验证该闭环是否合理。

如果存在

phase-plan.md

，验证仍仅聚焦于当前阶段。全功能的排期会为验证提供参考，但当前阶段的通过不代表后续阶段也获得批准。

Key Terms

关键术语

current phase: the slice being approved for execution now
whole-feature sequence: the broader multi-phase plan, if one exists
approval: permission to execute the current phase only, not to expand scope freely

current phase（当前阶段）：当前待审批可执行的片段
whole-feature sequence（全功能排期）：更宽泛的多阶段计划（如果存在）
approval（批准）：仅允许执行当前阶段，不代表可以随意扩大范围

Default Validation Loop

默认验证循环

confirm the current-phase artifacts and bead graph exist
retrieve prior learnings and orient to the current phase
run the 8-dimension structural check
inspect graph health and bead quality
run spikes only where hope is doing the work
summarize readiness in human terms
get explicit user approval before any code is written

Load

references/validation-operations.md

when you need the exact checker invocation, graph commands, spike mechanics, or handoff format.

确认当前阶段的产物和bead graph存在
调取之前的经验，对齐当前阶段的上下文
运行8维度结构检查
检查graph健康度和bead质量
仅在存在不确定性的环节运行spike
用自然语言总结就绪状态
编写任何代码前获得用户明确批准

当你需要确切的检查器调用方式、graph命令、spike机制或交接格式时，加载

references/validation-operations.md

。

Prerequisites

前置条件

Default checks:

bash

br show <EPIC_ID> --json
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>/plan.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

<HARD-GATE> If tasks do not exist in the bead graph, or `phase-contract.md` / `story-map.md` are truly missing, do not guess the plan into existence here. First verify the files were not misplaced, stale, or left partially written. If the planning package is genuinely incomplete, route back to `beo-planning`. </HARD-GATE>

默认检查项：

bash

br show <EPIC_ID> --json
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>/plan.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

<HARD-GATE> 如果bead graph中不存在任务，或是`phase-contract.md`/`story-map.md`确实缺失，不要在这里臆造计划。首先确认文件是否被错放、过期或未写完。如果规划包确实不完整，返回至`beo-planning`环节。 </HARD-GATE>

Phase 0: Learnings Retrieval + Current-Phase Orientation

阶段0：经验调取 + 当前阶段对齐

Before validating structure:

check institutional memory for relevant failure patterns
orient yourself to the current phase
if
```
phase-plan.md
```
exists, confirm how the current phase fits the larger whole plan

Load

references/validation-operations.md

for the exact orientation sequence and summary format when the default loop is not enough.

在验证结构前：

检查组织记忆库中相关的失败模式
对齐当前阶段的上下文
如果存在
```
phase-plan.md
```
，确认当前阶段如何适配整体大计划

当默认循环不够用时，加载

references/validation-operations.md

获取确切的对齐流程和总结格式。

Phase 1: Structural Verification

阶段1：结构验证

Check the current phase across 8 dimensions. For each dimension, assign PASS or FAIL.

从8个维度检查当前阶段。每个维度标记为通过或失败。

The 8 Dimensions

8个维度

#	Dimension	What to Check	FAIL if...
1	Phase contract clarity	`phase-contract.md` has clear entry state, exit state, demo story, unlocks, and scope	Exit state is vague or aspirational, demo does not prove the phase, phase sounds like a work bucket
2	Story coverage and ordering	`story-map.md` stories have purpose, why-now, contributes-to, unlocks, done-looks-like	A story cannot answer "what does this unlock?", order feels arbitrary, a needed story is missing
3	Decision coverage	Every `CONTEXT.md` decision (D1, D2...) maps to at least one story and bead	A locked decision appears nowhere in the story map, or a story mentions it but no bead implements it
4	Dependency correctness	Story order and bead dependencies agree, graph is acyclic	Story order says one thing but bead dependencies say another, cycles exist, implicit undeclared dependencies
5	File scope isolation	Parallel-ready beads don't silently collide	Two ready beads write the same file, config/schema files have no explicit owner
6	Context budget	Each bead fits in one worker context window	A bead spans multiple stories, requires reading too many large files, tries to implement an entire subsystem
7	Verification completeness	Stories and beads both have explicit done/verify criteria	Story "done" is vague, bead verify steps are not runnable, story completion depends on subjective judgment
8	Exit-state completeness and risk alignment	If all beads complete, the current phase reaches its exit state; HIGH-risk items have spike paths	Bead graph could finish while phase is not demoable, exit state depends on missing work, HIGH-risk items lack spikes

#	维度	检查内容	失败条件
1	阶段契约清晰度	`phase-contract.md` 包含明确的进入状态、退出状态、演示故事、解锁能力和范围	退出状态模糊或偏预期、演示无法证明阶段完成、阶段听起来像一个工作杂项桶
2	故事覆盖度和排序合理性	`story-map.md` 中的故事有明确目标、当前优先级、贡献项、解锁能力、完成标准	某个故事无法回答「这能解锁什么？」、排序感觉随意、缺少必要的故事
3	决策覆盖度	每个 `CONTEXT.md` 中的决策（D1、D2...）至少对应一个故事和bead	已锁定的决策未出现在故事地图中，或是故事提到了决策但没有bead实现它
4	依赖正确性	故事顺序和bead依赖一致，graph无环	故事顺序和bead依赖矛盾、存在循环、存在未声明的隐式依赖
5	文件范围隔离	支持并行的bead不会隐性冲突	两个待执行的bead写入同一个文件、配置/ schema文件没有明确负责人
6	上下文预算	每个bead可以放在单个工作者的上下文窗口内	一个bead横跨多个故事、需要读取过多大文件、试图实现整个子系统
7	验证完整性	故事和bead都有明确的完成/验证标准	故事的「完成」定义模糊、bead验证步骤不可运行、故事完成依赖主观判断
8	退出状态完整性和风险对齐	如果所有bead都完成时，当前阶段能达到退出状态；高风险项有spike路径	bead graph全部完成但阶段仍无法演示、退出状态依赖缺失的工作、高风险项没有spike

Running the Check

运行检查

Load

references/validation-operations.md

for the exact plan-checker invocation, repair routing, and failure-handling loop.

Default repair rule: fix 1-2 structural failures in place, but if failures keep cascading or the current phase stops making sense as a closed loop, stop patching and route back to planning.

加载

references/validation-operations.md

获取确切的计划检查器调用方式、修复路径和失败处理循环。

默认修复规则：就地修复1-2个结构缺陷，但如果缺陷持续连锁出现，或是当前阶段作为闭环已经不合理，停止修补返回至规划环节。

Repair Routing by Failure Type

按失败类型的修复路径

Failure Type	Route Back To
Exit state is vague or current-phase meaning is weak	`phase-contract.md`
Story order or story coverage is weak	`story-map.md`
Locked decisions are not mapped into implementation	`approach.md` , `plan.md` , stories, and bead descriptions
Dependency graph is inconsistent or cyclic	bead dependency wiring
Parallel beads silently collide on files	bead ownership, bead split, or story decomposition
Bead scope exceeds one worker context	bead decomposition
Verification is vague or subjective	story and bead verification criteria
HIGH-risk work has no proof path	spike design or broader planning revision
Current phase no longer fits the larger feature sequence	`phase-plan.md` , `approach.md` , and current-phase artifacts

失败类型	返回至
退出状态模糊或当前阶段意义不明确	`phase-contract.md`
故事顺序或故事覆盖度不足	`story-map.md`
已锁定决策未映射到实现中	`approach.md` 、 `plan.md` 、故事和bead描述
依赖图不一致或存在循环	bead依赖配置
并行bead在文件上隐性冲突	bead所有权、bead拆分或故事分解
bead范围超出单个工作者上下文	bead分解
验证模糊或主观	故事和bead验证标准
高风险工作没有验证路径	spike设计或更全面的规划修订
当前阶段不再适配整体功能排期	`phase-plan.md` 、 `approach.md` 和当前阶段产物

Phase 2: Graph Health

阶段2：Graph健康度

Use

bv

to analyze the bead graph for structural issues.

Load

references/validation-operations.md

for the exact commands, interpretation table, deduplication check, story-to-bead coherence check, and bead-description verification procedure.

Minimum graph-health pass:

inspect suggestions and cycles with
```
bv
```
verify every story maps to at least one bead
verify every bead belongs to this current phase
verify every bead description is specific enough for a fresh worker

<HARD-GATE> FAIL the plan if any bead has an empty or underspecified description. This is a structural verification failure, not an optional quality note. If only one or two beads are thin but the phase shape is sound, tighten those specs directly or send them back for planning repair. If the thin specs expose a larger decomposition problem, route back to `beo-planning`. </HARD-GATE>

使用

bv

分析bead graph的结构问题。

加载

references/validation-operations.md

获取确切的命令、释义表、去重检查、故事到bead的一致性检查和bead描述验证流程。

最低graph健康度通过标准：

使用
```
bv
```
检查建议和循环
验证每个故事至少对应一个bead
验证每个bead都属于当前阶段
验证每个bead的描述对新工作者来说足够明确

<HARD-GATE> 如果任何bead的描述为空或描述不足，计划验证失败。这是结构验证失败，不是可选的质量提示。如果只有1-2个bead描述不够详细但阶段结构合理，可以直接完善这些规格，或是返回规划环节修复。如果描述不足暴露了更大的分解问题，返回至`beo-planning`。 </HARD-GATE>

Phase 3: Spike Execution (HIGH-Risk Only)

阶段3：Spike执行（仅高风险项）

For each HIGH-risk task, evaluate whether a spike is needed.

A spike is needed when the approach is unproven, depends on external systems, has hard performance requirements, or otherwise relies on hope.

Load

references/validation-operations.md

for the exact create/record/result-handling sequence.

Default spike rule: only spike when a yes/no proof would change whether this phase should proceed. Do not create ceremonial spikes for already-understood work.

<HARD-GATE> A spike NO result means the current phase plan is invalid. Do not proceed to approval. </HARD-GATE>

对每个高风险任务，评估是否需要spike。

当方案未经验证、依赖外部系统、有严格的性能要求，或是其他存在不确定性的场景，需要spike。

加载

references/validation-operations.md

获取确切的创建/记录/结果处理流程。

默认spike规则：仅当是/否的验证结果会影响当前阶段是否继续时才运行spike。不要为已经明确的工作创建形式化的spike。

<HARD-GATE> Spike结果为否意味着当前阶段计划无效。不得进入审批环节。 </HARD-GATE>

Phase 4: Fresh-Eyes Review (Optional)

阶段4：新视角评审（可选）

For deep complexity features or features with 5+ tasks, load

references/validation-operations.md

for the exact fresh-eyes review procedure.

对于深度复杂功能或任务数超过5个的功能，加载

references/validation-operations.md

获取确切的新视角评审流程。

Phase 5: Exit-State Readiness Review

阶段5：退出状态就绪评审

This is the human-readable readiness check before approval.

Ask these questions explicitly:

If all stories reach "Done Looks Like", does the current phase exit state hold?
If all beads close successfully, will all stories actually be done?
Is the current phase demo story now credible?
If
```
phase-plan.md
```
exists, does this current phase still make sense inside the larger whole plan?

If any answer is "no" or "not sure", do not approve execution. Route back:

Problem	Route To
Current-phase meaning / exit state problem	Revise `phase-contract.md`
Story decomposition problem	Revise `story-map.md`
Implementation granularity problem	Revise bead descriptions
Architecture / risk problem	Revise `approach.md` , `plan.md` , and possibly route to `beo-planning`
Whole-feature sequencing problem	Revise `phase-plan.md` and current-phase artifacts

这是审批前的人类可读的就绪检查。

明确询问以下问题：

如果所有故事都达到「完成标准」，当前阶段的退出状态是否能达成？
如果所有bead都成功关闭，所有故事是否确实完成？
当前阶段的演示故事现在是否可信？
如果存在
```
phase-plan.md
```
，当前阶段是否仍然适配整体大计划？

如果任何答案是「否」或「不确定」，不要批准执行。返回对应环节：

问题	返回至
当前阶段意义/退出状态问题	修订 `phase-contract.md`
故事分解问题	修订 `story-map.md`
实现粒度问题	修订bead描述
架构/风险问题	修订 `approach.md` 、 `plan.md` ，可能返回至 `beo-planning`
全功能排期问题	修订 `phase-plan.md` 和当前阶段产物

Phase 6: Approval Gate

阶段6：审批关口

<HARD-GATE> Use the canonical validation approval rule from `../reference/references/approval-gates.md`: user approval is required before any code is written. This is non-negotiable. </HARD-GATE>

Load

references/validation-operations.md

for the exact approval summary, approval commands, rejection handling, and route-back rules.

<HARD-GATE> 使用`../reference/references/approval-gates.md`中的标准验证审批规则：编写任何代码前必须获得用户批准。此规则不可协商。 </HARD-GATE>

加载

references/validation-operations.md

获取确切的审批总结、审批命令、驳回处理和返回规则。

Lightweight Mode

轻量模式

Load

references/validation-operations.md

for the lightweight-validation shortcut, context-budget checkpoint procedure, and canonical handoff flow.

加载

references/validation-operations.md

获取轻量验证快捷方式、上下文预算检查点流程和标准交接流程。

Context Budget

上下文预算

If context usage exceeds 65%, use the checkpoint procedure from

references/validation-operations.md

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

references/validation-operations.md

中的检查点流程。

Handoff

交接

After user approves, use

references/validation-operations.md

to determine execution mode and write the canonical

STATE.md

handoff.

Announce:

text

Current phase approved. <N> tasks ready for execution.
Execution mode: <single-worker | parallel (swarming)>
Load <beo-executing | beo-swarming> to begin implementation.

planning_mode = multi-phase

, current-phase approval does not imply feature completion. Later phases remain deferred until routed back through

beo-planning

See

references/validating-guardrails.md

for red flags and anti-patterns.

用户批准后，使用

references/validation-operations.md

确定执行模式并编写标准的

STATE.md

交接文件。

公告：

text

Current phase approved. <N> tasks ready for execution.
Execution mode: <single-worker | parallel (swarming)>
Load <beo-executing | beo-swarming> to begin implementation.

如果

planning_mode = multi-phase

，当前阶段的批准不代表功能完成。后续阶段仍需返回

beo-planning

流程后再推进。

查看

references/validating-guardrails.md

了解风险提示和反模式。