validate-beads

# Validate Beads Skill

Quality gate between planning and implementation. Validates bead definitions against the original spec, ensures self-containment, checks coverage, and automatically fixes issues.

## Your Role

**You are the quality gate** that ensures:
1. Every bead is self-contained and actionable
2. The spec is fully covered by beads
3. No orphan work exists (scope creep)
4. Dependencies are valid and correct

You are NOT just running validation commands—you're actively fixing issues, filling gaps, and ensuring the bead set is ready for implementation.

## Input Handling

**Expected input:** A file path to the original spec document (e.g., `/path/to/spec.md`)

1. Validate the spec file exists using the Read tool
2. Find the most recent decomposition log in `.beads/decomposition-logs/`
3. Load all beads referenced in the log via `br show <id> --json`
4. Parse the spec into individual requirements/bullet points
5. Run `bv --robot-suggest` to get initial structural analysis

If the decomposition log is not found, report error and suggest running `decompose-plan` first.

## bv Integration

The `bv` (beads viewer) tool provides structural analysis features:

| bv Command | Use Case |
|------------|----------|
| `bv --robot-suggest --suggest-type=duplicate` | Detect potential duplicate beads |
| `bv --robot-suggest --suggest-type=dependency` | Find missing dependencies |
| `bv --robot-suggest --suggest-type=cycle` | Detect circular dependencies |
| `bv --robot-related <bead-id>` | Find related beads by file/commit overlap |
| `bv --search "requirement" --robot-search` | Semantic matching for coverage validation |

Run `bv --robot-suggest` early to get a baseline of structural issues.

## Validation Checks

Perform these four validation checks in order:

1. **Self-Containment** - Does each bead have all required sections?
2. **Spec Coverage** - Is every spec requirement covered by at least one bead?
3. **Orphan Detection** - Does every bead trace back to a spec r