| 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. |
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
bv --robot-triage
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
bv --robot-triage | jq '.recommendations[0]'
br update bd-123 --status in_progress
br close bd-123 --reason "Implemented in abc123"
bv --robot-triage
Scoping & Filtering
bv --robot-plan --label backend
bv --robot-insights --as-of HEAD~30
bv --recipe actionable --robot-plan
bv --recipe high-impact --robot-triage
bv --robot-triage --robot-triage-by-track
bv --robot-triage --robot-triage-by-label
bv --robot-alerts --severity=critical
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
br create "Title" -d "desc"
br update bd-123 --status in_progress
br close bd-123 --reason "Done"
br dep add bd-123 bd-456
br dep remove bd-123 bd-456
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
bv --robot-triage >/dev/null && br list >/dev/null && echo "OK"
bv --robot-insights | jq '{cycles: .Cycles, density: .density}'
References