beads-validation

name	beads-validation
description	Validates beads issues after creation. Checks dependencies, PRD mapping, order, and issue quality. Use when: after creating issues, before TDD loop, before handoff. Triggers: "validate beads", "check issues", "verify tasks", "check quality", "validate handoff".

Beads Validation Skill

Validates that beads issues are correctly created and ready for TDD.

When to Use

1. After creating issues (in rust-project-init):

   • Check all PRD features have corresponding issues
   • Check priorities are valid
   • Check issue IDs exist before adding dependencies

2. Before TDD loop (in /ship Phase 2.5):

   • Check for circular dependencies
   • Check bd ready returns expected first task
   • Check no issues are incorrectly blocked

Validation Checks

1. PRD → Issues Mapping

# Count features in PRD
grep -c "^###\|^-" docs/PRD.md | head -1

# Count issues created
bd list --status=open | wc -l

# Each MVP feature should have an issue

2. Dependency Validity

# List all dependencies
bd list --status=open --json | jq '.[] | .dependencies'

# Check each dependency ID exists
bd show {dep_id}  # Should not error

3. Circular Dependency Check

# bd doctor checks for cycles
bd doctor

4. Ready State Check

# Should have at least one ready issue
bd ready --limit=1

# If empty, something is blocked incorrectly

5. Priority Validation

# All priorities should be 0-4
bd list --json | jq '.[] | .priority' | sort -u

6. Issue Quality Check (NEW)

# Check all open issues have required sections
python3 scripts/validate_beads.py --check-quality

Validates that issues are self-contained:

• Minimum length: Description > 100 characters
• Summary section: Overview, Goal, or clear opening statement
• Files section: Specific paths mentioned
• Steps section: Implementation steps (numbered list)
• Criteria section: Acceptance criteria or checkboxes

Script Usage

# After creating issues
python3 scripts/validate_beads.py --check-created --prd docs/PRD.md

# Before TDD
python3 scripts/validate_beads.py --check-deps --check-ready

# Check issue quality (for handoff)
python3 scripts/validate_beads.py --check-quality

# Full validation (all checks)
python3 scripts/validate_beads.py --all --prd docs/PRD.md

Output:

## Beads Validation

[PASS] PRD features: 4, Issues created: 4
[PASS] All dependency IDs exist
[PASS] No circular dependencies
[PASS] Ready queue has 1 issue (notes-abc)
[PASS] All 4 open issues pass quality check
[PASS] All priorities valid (0-4)

Result: 6/6 checks passed

Quality check failure output:

## Beads Validation

[WARN] 2/4 issues have quality problems

  Quality issues:
    task-abc:
      - Description too short (45 chars, need 100+)
      - Missing Acceptance Criteria section
    task-xyz:
      - Missing Files to Modify section

Common Issues

No Ready Issues

[FAIL] No issues ready to work on

Cause: All issues blocked by dependencies Fix: Check dependency chain, ensure at least one issue has no blockers

Missing Features

[WARN] PRD has 5 features, only 3 issues created

Fix: Create missing issues with bd create

Invalid Dependency

[FAIL] Dependency notes-xyz does not exist

Fix: Check issue ID before bd dep add

Circular Dependency

[FAIL] Circular dependency: A → B → C → A

Fix: Remove one dependency to break cycle

Low Quality Issue

[WARN] task-abc: Description too short (45 chars, need 100+)
[WARN] task-abc: Missing Files to Modify section

Fix: Use bd edit <id> --description and follow the template from beads-workflow/references/issue-template.md

Integration

Called automatically in:

• rust-project-init.md → After creating issues
• ship.md → Phase 2.5: Before TDD loop
• beads-workflow → Before handoff (Phase 5)