Review Beads

Review Beads: Adversarial Bead Compliance Review

Philosophy: "If I hand this bead to an agent with no other context, will it build the software correctly?" Every finding must pass a second filter: "Am I sure this is actually wrong, or does it just look different from what I expected?" False positives erode trust faster than missed defects.

Duration targets: BRIEF ~15-20 minutes (single entity, Fallback: Only if AskUserQuestion is not available as a tool (check your tool list), fall back to presenting options as markdown text and waiting for freeform response.

Shared References

Before starting any review, load these shared reference files:

• CONVERGE loop & classification: ../_shared/references/converge-mode.md
• Severity model & finding quality: ../_shared/references/review-finding-taxonomy.md

These define the CONVERGE mode behavior, MECHANICAL vs DECISION classification, authority hierarchy, PRE_EXISTING severity rules, and finding quality standards shared across all review skills. Skill-specific CONVERGE behavior (wave definitions, authority hierarchy overrides) is documented inline below.

---

Mode Selection

| Mode | When | Scope | |------|------|-------| | BRIEF | Single entity/feature, Pattern docs > Architecture docs > Design (api-surface, data-model) > PRD (FRs, UCs, ACs) > Plan (overview, sub-plans) > Beads

**Dependency minimization is intentional.** When CONVERGE encounters a dependency graph that doesn't match the pattern decomposition tables' full ordering (e.g., Contracts has no edge to EF Config, Validators have no edge to Commands), verify compile-time necessity before adding edges. The `/beads` skill's Step 1.4b explicitly prunes pattern-sequence edges to compile-order edges for multi-agent parallelism. Adding unnecessary dependency edges to match the pattern table's logical sequence is itself a `WRONG_DEPENDENCY` finding — it serializes work that should be parallel.

**Same-session detection:** If beads were generated in the current conversation, flag as same-session. Increase spot-checks to 5 minimum. Phase 2 confidence is LOW.

**Non-greenfield bead review:** If the plan's Implementation Status shows >70% "Exists":
- Verification beads ("verify X matches design") may omit Failure Criteria — the success criteria checklist IS the constraint
- "Modify" beads should specify WHAT needs to change, not just the endpoint/entity name
- Do NOT flag verification beads as incomplete because they lack implementation guidance

**Do NOT delegate finding generation to Explore agents.** Agents cannot call `br show` to read actual bead text — they guess at content and produce 80%+ false positive rates. Generate findings in the main context where `br show` is available. Use agents only for loading upstream docs (PRD, design, ADRs), not for reviewing bead content.

**Verification Mode Phase 3 shortcut:** For >90% exists, skip the greenfield decomposition tables (entity × bead types). Instead: verify bead count matches plan task count, check for over-combined tasks against grouping rules. The plan already determined appropriate granularity.

**Non-CRUD granularity method:** For infrastructure/shell modules (no entities to CRUD), count expected beads from: services, guards, interceptors, initializers, layout components, utility components. Map these to bead expectations instead of entity decomposition tables.

**Compact report for 0-FAIL results:** When Round 1 produces 0 FAILs, use the compact format by default. The full report template (FR matrix, UC matrix, stage gate analysis) is only needed when there are unresolved FAILs or DECISION items.

**False positive log:** Include a `## False Positives Dismissed` section in the review report documenting which findings were dismissed and why. This makes review quality auditable and helps calibrate future reviews.

**Auto-downgrade:** COMPREHENSIVE on a single module automatically uses STANDARD depth regardless of bead count. Batch execution sections only apply to multi-module reviews. Apply this downgrade BEFORE document loading begins.

**Verification Module fast path (>90% exists, any bead count):** Skip Phase 2 (FR/UC coverage inherited from plan) and Phase 3 (greenfield decomposition tables irrelevant). Go straight to Phase 4 (bead-by-bead) + Phase 5 (cross-bead consistency). Use compact report by default. The bead count threshold (was ≤10) is removed — what matters is that >90% of design elements exist, not how many beads there are.

**Wave 1 only for non-greenfield (>70% exists):** Load bead file + design API surfaces first. Only load PRD/UCs/mockups if Wave 1 reveals coverage gaps. This cuts document loading by ~60% for modification-only bead sets.

**Category applicability by bead type:** Not all 11 categories apply to all bead types:
- **Implementation beads:** All 11 categories apply
- **Verification beads:** Categories 1-2 (coverage), 7b (gates), 8 (quality), 10 (cross-module) apply. Skip 3-6 (design/pattern compliance for new code), 9 (backwards compat), 11 (granularity).
- **Test beads:** Categories 7b (gates), 8 (quality) apply. Skip most others.
- **Gate beads:** Category 7b only.

**br is the single source of truth.** The /beads skill writes full structured descriptions (Objective through Verification) directly into each br record via `br update {id} --description`. Hive's BeadsAdapter reads `br show --json` and passes `bead.Description` directly to executing agents. When reviewing, read bead content from `br show {id} --json` — this is the authoritative record. beads.md, if it exists, is a derived export and may be stale. When CONVERGE fixes a bead, update br directly with `br update {id} --description "{corrected content}"` — do not edit beads.md first.

**Token budget:** COMPREHENSIVE reviews with 50+ beads read 30-60 documents. Models with `) before writing any finding — do not flag based on cached/stale reads
2. **Quote the specific defect** from the bead text — "the bead says X" or "the bead omits X"
3. **Check br description field AND wired dependencies** — verify `br show  --json` `.description` contains the full structured content; verify `br dep list ` for dependency findings
4. **Verify against the authoritative source doc**, not the plan — plans are lower trust than designs (see Trust Hierarchy in `/beads` skill)
5. **The issue must cause a concrete problem during execution** — "an agent executing this bead would produce [wrong outcome]" or "an agent would have to guess about [ambiguous thing]"

### What NOT to Flag

- **Missing ADR references that CLAUDE.md already covers** — CLAUDE.md is always loaded; referencing ADRs it already mandates is redundant
- **Missing global pattern references** — i18n, toast notifications, error handling patterns that are project-wide conventions agents already follow
- **Redundant transitive dependencies** — if A depends on B and B depends on C, A does not need to explicitly depend on C
- **Description style preferences** — ordering of sections, wording choices, formatting variations
- **Intentionally minimized dependencies for parallelism** — if a bead omits a pattern-sequence dependency (e.g., Contracts doesn't depend on EF Config, Validators don't depend on Commands) but the omission doesn't create a compile error, this is correct parallelism optimization, not a missing dependency. Only flag `WRONG_DEPENDENCY` when the missing edge would cause a compilation failure or runtime error during execution. The `/beads` skill's Step 1.4b explicitly prunes pattern-sequence edges to compile-order edges.
- **Soft checkpoint gates without `br dep add` edges** — the `/beads` skill distinguishes hard gates (dependency edges) from soft checkpoints (advisory notes). A UC verify gate or module completion gate without wired dependencies is intentional, not an `ORPHANED_GATE`.
- **Issues in upstream docs** — tag as `UPSTREAM_DOC` and list separately; these are not bead defects

---

## Trust Hierarchy

When reviewing beads, verify against sources in this order (highest trust first):

1. **ADRs & Pattern docs** — architectural intent, non-negotiable
2. **Design docs** (api-surface, data-model, ui-mockup) — technical specification (refined from PRD)
3. **PRD** — business requirements, Must-Have FRs
4. **Use cases** — actor workflows, extension/alternative flows
5. **Plans & Sub-plans** — implementation breakdown (lower trust — may have drifted)
6. **Beads** — must conform to everything above

If a bead contradicts a higher-trust source, the bead is wrong. If a plan contradicts the design, cite the design, not the plan. If a PRD and design disagree, the design is authoritative — it represents the refined technical decision derived from the PRD.

---

## Finding Classification

Every finding has a **class** (what's wrong) and a **severity** (FAIL or WARN):

| Class | Meaning | Default Severity |
|-------|---------|-----------------|
| `MISSING_BEAD` | Required bead does not exist | **FAIL** |
| `WRONG_CONTENT` | Bead exists but description is incorrect | **FAIL** |
| `WRONG_DEPENDENCY` | Dependency wiring is incorrect | **FAIL** |
| `EMPTY_GATE` | Gate bead has no scope or verification commands | **FAIL** |
| `ORPHANED_GATE` | Gate bead exists but nothing depends on it | **WARN** |
| `WRONG_TYPE` | Bead type is incorrect | **WARN** |
| `GRANULARITY` | Bead is too coarse or too fine | **WARN** |
| `STALE_REF` | Context reference points to wrong/missing file | **FAIL** (MECHANICAL — auto-fixable) |
| `CROSS_MODULE` | Cross-module dependency not wired | **FAIL** |
| `UPSTREAM_DOC` | Issue is in the upstream doc, not the bead | **WARN** (not a bead defect — note separately) |
| `DESCRIPTION_DRIFT` | br description is empty or stub (missing structured content) | **FAIL** (agents get no objective) |

**Severity model alignment:** This skill uses FAIL/WARN for finding classification (matching review-prd, review-design, review-plan). FAIL = blocks /execute. WARN = quality improvement, doesn't block.

**Report severity mapping:** The review report uses a four-tier severity (CRITICAL/HIGH/MEDIUM/LOW) as a refinement of FAIL/WARN for prioritizing remediation:

| Report Severity | Finding Class | Meaning |
|----------------|--------------|---------|
| CRITICAL | FAIL | Build won't compile, data wrong, security vulnerable, Must-Have FR missing |
| HIGH | FAIL | Agent will guess wrong — incorrect results caught only at review/test time |
| MEDIUM | WARN | Agent likely succeeds but may be confused or produce suboptimal output |
| LOW | WARN | Cosmetic or minor quality issues, no execution impact |

CONVERGE auto-fixes all FAILs (CRITICAL + HIGH). WARNs (MEDIUM + LOW) are listed but not auto-fixed unless trivial.

---

## Severity Calibration

**Every finding gets a severity. Calibrate carefully — inflation kills trust.**

### CRITICAL

The build won't compile, data will be wrong, security is vulnerable, a Must-Have FR is violated, or a required bead is missing entirely. An agent executing the bead set will produce broken software.

Examples:
- Must-Have FR has zero bead coverage
- Bead references entity property that doesn't exist in data model
- Missing bead for entity that other beads depend on
- Security-sensitive endpoint has no authorization bead
- Bead wires to wrong entity (Role bead references Permission table)

### HIGH

An agent will guess wrong. The bead provides enough information to execute, but the execution will produce incorrect results that won't be caught until review or testing.

Examples:
- Empty gate bead — no file paths, no verification commands
- Orphaned gate — gate exists but nothing blocks on it
- Stale context reference — file moved or renamed
- Wrong pattern reference — bead says `commands` pattern but should be `queries`
- Missing dependency — bead will fail because prerequisite doesn't exist yet
- Frontend bead depends on backend impl bead instead of test gate

### MEDIUM

An agent would likely succeed but could be confused, leading to suboptimal implementation or wasted time asking questions.

Examples:
- Bead objective is ambiguous — two valid interpretations
- Success criteria are vague — "works correctly" instead of testable outcomes
- Missing out-of-scope section — agent might drift into adjacent work
- Bead combines two small pattern artifacts that COULD be separate (borderline grouping)

### LOW

Cosmetic or minor quality issues that don't affect execution.

Examples:
- Inconsistent bead title convention
- Missing FR tag that's obvious from context
- Verification command uses wrong test filter (but close)
- Bead could reference a learning doc but doesn't need to

---

## Critical Sequence

### Phase 1: Document Loading

**ID format note:** Examples throughout this skill use `bd-001`, `bd-006`, etc. as illustrative placeholders. `br` assigns its own IDs. Always use the actual IDs from `br list --json` — do not construct IDs manually.

**Load every upstream document before reviewing any bead** (except in CONVERGE mode with >70% exists — use progressive loading per Wave 1 guidance above). Do not start reviewing beads until source material is loaded.

**Step 1.1 — Identify the feature and bead set:**

```bash
br list --status open --json   # or filter by epic
br dep tree           # dependency visualization

Record: epic ID, bead count, feature name.

Step 1.1b — Verify br descriptions are populated (HARD STOP):

Before loading ANY upstream documents, verify every bead has a populated description.

Important: br list --json may not include full description text (some versions return summaries only). If the script below reports all OK but you suspect descriptions are missing, verify with br show {id} --json for individual beads — the .description field in br show is always the full content.

br list --status open --json | python3 -c "
import sys, json
beads = json.load(sys.stdin)
empty = [b for b in beads if not b.get('description','').strip()]
if empty:
    print(f'HARD STOP: {len(empty)} of {len(beads)} beads have empty descriptions.')
    print('Cannot review — agents would receive no objective.')
    for b in empty:
        print(f'  {b[\"id\"]}: {b[\"title\"][:60]}')
    print()
    print('Resolution: re-run /beads, or for each empty bead:')
    print('  br update {id} --description \"{full structured content}\"')
    sys.exit(1)
else:
    print(f'OK: all {len(beads)} beads have populated descriptions')
"

If ANY bead has an empty description, STOP immediately. Do NOT proceed to Phase 2, do NOT load upstream documents, do NOT build coverage matrices. The entire review is wasted effort if bead descriptions are missing — report the count, list the empty beads, and tell the user to re-run /beads or manually populate descriptions.

Step 1.2 — Load upstream documents:

Read ALL of the following that exist (use the project's doc structure):

| Document | Path Pattern | Purpose | |----------|-------------|---------| | PRD | docs/prd/{feature}/prd.md | FR definitions, acceptance criteria, priorities | | Design — API surface | docs/designs/{feature}/**/api-surface.md | Endpoints, shapes, HTTP methods, error responses | | Design — Data model | docs/designs/{feature}/**/data-model.md | Entities, properties, constraints, relationships | | Design — UI mockup | docs/designs/{feature}/**/ui-mockup.md | Screens, components, interactions, states | | Design — Test plan | docs/designs/{feature}/**/test-plan.md | Test scenarios, coverage matrix | | Design — Overview | docs/designs/{feature}/design.md | Problem statement, constraints, chosen approach | | Use cases | docs/use-cases/UC-*.md | Actor workflows, extension flows, error conditions | | Plan overview | docs/plans/{feature}/overview.md | Task summary, dependency graph, FR coverage | | Sub-plans | docs/plans/{feature}/[0-9]*.md | Per-task intent, scope, criteria | | Pattern docs | docs/patterns/**/*.md | Pattern keys referenced by beads | | A

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dirkkok101
• Source: dirkkok101/skills
• License: MIT

Install and usage instructions live in the source repository linked above.