beads-bv - SKILL.md Agent Skill

name: beads-bv description: 'Graph-aware task triage with bv and br. Use when prioritizing work, finding bottlenecks, tracking dependencies, or managing local issues across projects. Triggers: "beads-bv", "beads bv", "graph-aware task triage with bv".'

beads-bv — Graph-Aware Triage

Core Insight: Your backlog is a directed graph. PageRank finds what everything depends on. Betweenness finds bottlenecks. The math knows your priorities better than your gut.

CRITICAL: Robot Mode Only

bv                    # WRONG — launches TUI, blocks terminal
bv --robot-triage     # CORRECT — JSON output for agents

NEVER run bare bv in agent contexts.

Commands

Core (Start Here)

Command	Returns	Use When
`--robot-triage`	THE MEGA-COMMAND: recommendations + blockers + health	What should I work on?
`--robot-next`	Single top pick + claim command	Just the one thing
`--robot-plan`	Parallel execution tracks with `unblocks`	What can run concurrently?
`--robot-insights`	All metrics + cycles + density + k-core + slack	Deep analysis
`--robot-priority`	Priority misalignments with confidence	Am I prioritizing wrong?

Labels & Health

Command	Returns	Use When
`--robot-label-health`	Per-label: health_level, velocity, staleness	Which domain is struggling?
`--robot-label-flow`	Cross-label dependencies, bottleneck_labels	Inter-team blockers
`--robot-label-attention`	Attention-ranked labels	Where to focus?
`--robot-alerts`	Stale issues, blocking cascades, priority mismatches	What's rotting?
`--robot-suggest`	Duplicates, missing deps, cycle breaks	Hygiene

History & Correlation

Command	Returns	Use When
`--robot-history`	Bead-to-commit correlations	Change tracking
`--robot-causality <id>`	Timeline, blockers, insights	Why did this take so long?
`--robot-related <id>`	File/commit overlap, clusters	What's connected?
`--robot-file-beads <path>`	Beads that touched a file	Code ownership

Time-Travel & Search

Command	Returns	Use When
`--robot-diff --diff-since <ref>`	New/closed/modified since ref	What changed?
`--as-of <ref>`	Historical point-in-time	Time-travel
`--robot-search`	Search results as JSON	Find beads
`--search-mode hybrid`	Text + graph ranking	Smart search

Full command reference: COMMANDS.md

Workflow

# 1. What should I work on?
bv --robot-triage | jq '.recommendations[0]'

# 2. Claim it
br update bd-123 --status in_progress

# 3. Do the work...

# 4. Done
br close bd-123 --reason "Implemented in abc123"

# 5. Next
bv --robot-triage

Scoping & Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Only unblocked items
bv --recipe high-impact --robot-triage       # Top PageRank scores
bv --robot-triage --robot-triage-by-track    # Group by parallel streams
bv --robot-triage --robot-triage-by-label    # Group by domain
bv --robot-alerts --severity=critical        # Filter alerts

Key Metrics

Metric	High Score Means
PageRank	Everything depends on this — fix first
Betweenness	Bottleneck — blocks multiple paths
Cycles	Broken graph — fix immediately
K-Core	Structural strength (core membership)
Articulation	Cut vertex — removal disconnects graph

Decision Matrix

Pattern	Meaning	Action
High PageRank + High Betweenness	Critical bottleneck	Drop everything, fix this
High PageRank + Low Betweenness	Foundation piece	Important but not blocking
Low PageRank + High Betweenness	Unexpected chokepoint	Investigate why

Full metrics: METRICS.md

br Essentials

br ready --json                              # What's unblocked?
br create "Title" -d "desc"                  # New issue
br update bd-123 --status in_progress        # Working on this
br close bd-123 --reason "Done"              # Done
br dep add bd-123 bd-456                      # Add dependency
br dep remove bd-123 bd-456                   # Break cycle

Troubleshooting

Problem	Cause	Fix
`bv` hangs	TUI launched	Use `--robot-*` flags
Cycles detected	Circular dependency	`br dep remove` to break
Phase 2 timeout	Large graph (>500 nodes)	Check `status` field
Empty metric maps	Phase 2 still running	Check `status` flags
Inconsistent outputs	Different data	Compare `data_hash`

Validation

# Tools working?
bv --robot-triage >/dev/null && br list >/dev/null && echo "OK"

# Graph healthy?
bv --robot-insights | jq '{cycles: .Cycles, density: .density}'
# cycles must be [], density < 0.3 is healthy

References

Need	Read
All robot commands + flags	COMMANDS.md
All metrics explained	METRICS.md
jq recipes, morning triage	RECIPES.md