beads-bv

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