Beo Validating
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.
If
exists, validating still focuses on the
current phase only. Whole-feature sequencing informs the validator, but current-phase approval does not approve later phases.
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
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.
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>
Phase 0: Learnings Retrieval + Current-Phase Orientation
Before validating structure:
- check institutional memory for relevant failure patterns
- orient yourself to the current phase
- if 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 1: Structural Verification
Check the current phase across 8 dimensions. For each dimension, assign PASS or FAIL.
The 8 Dimensions
| # | Dimension | What to Check | FAIL if... |
|---|
| 1 | Phase contract clarity | 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 | 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 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 |
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.
Repair Routing by Failure Type
| Failure Type | Route Back To |
|---|
| Exit state is vague or current-phase meaning is weak | |
| Story order or story coverage is weak | |
| Locked decisions are not mapped into implementation | , , 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 | , , and current-phase artifacts |
Phase 2: Graph Health
Use
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
- 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>
Phase 3: Spike Execution (HIGH-Risk Only)
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>
Phase 4: Fresh-Eyes Review (Optional)
For
deep complexity features or features with 5+ tasks, load
references/validation-operations.md
for the exact fresh-eyes review procedure.
Phase 5: Exit-State Readiness Review
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 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 |
| Story decomposition problem | Revise |
| Implementation granularity problem | Revise bead descriptions |
| Architecture / risk problem | Revise , , and possibly route to |
| Whole-feature sequencing problem | Revise and current-phase artifacts |
Phase 6: Approval Gate
<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.
Lightweight Mode
Load
references/validation-operations.md
for the lightweight-validation shortcut, context-budget checkpoint procedure, and canonical handoff flow.
Context Budget
If context usage exceeds 65%, use the checkpoint procedure from
references/validation-operations.md
.
Handoff
After user approves, use
references/validation-operations.md
to determine execution mode and write the canonical
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.
If
planning_mode = multi-phase
, current-phase approval does not imply feature completion. Later phases remain deferred until routed back through
.
See
references/validating-guardrails.md
for red flags and anti-patterns.