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 |
majiayu000