bv Skill: AI-Driven Issue Tracker Analysis

Overview

bv (beads_viewer) is a high-performance Go TUI for analyzing beads issue tracker dependency graphs. This skill enables AI agents to leverage bv's robot protocol for intelligent task prioritization, dependency analysis, and architectural health monitoring.

Key Principle: NEVER launch the interactive TUI. Always use --robot-* flags for structured JSON output.

When to Use This Skill

Activate this skill when:

Task Prioritization

"What should I work on next?"
"Which issues are blocking the most work?"
"What's the highest impact task?"
Sprint planning and backlog grooming

Dependency Analysis

"What depends on this issue?"
"What are the dependencies for this feature?"
"What will this unblock?"
Understanding sequential vs parallelizable work

Project Health Monitoring

"Is the project architecture healthy?"
"Are there circular dependencies?"
"Is the codebase too coupled?"
Detecting architectural drift in CI/CD

Architectural Refactoring

"What are the bottlenecks?"
"Which issues should we refactor first?"
"How can we reduce coupling?"
Identifying technical debt

Historical Analysis

"What changed since last sprint?"
"Is project health improving or degrading?"
"How has complexity evolved?"
Release retrospectives

Core Capabilities

1. Graph Metrics (9 Dimensions)

bv computes comprehensive metrics for every issue:

Metric	Meaning	Use Case
PageRank	Blocking power	Foundational dependencies
Betweenness	Bottleneck status	Bridge issues between work streams
HITS (Hub/Authority)	Dependency nature	Integration vs foundation work
Critical Path	Chain depth	Sequential dependency length
Eigenvector	Network influence	Importance of connected issues
Degree	Connection count	Direct dependencies
Density	Coupling measure	Overall graph health
Cycles	Circular dependencies	Architectural problems
Topological Sort	Valid execution order	Can work be sequenced?

See principles/graph-metrics.md for detailed explanations.

2. Robot Protocol Commands

All commands return structured JSON for programmatic analysis:

Analysis Commands

# Comprehensive metrics
bv --robot-insights

# Execution plan with recommendations
bv --robot-plan

# Priority adjustment suggestions
bv --robot-priority

# Available filtering recipes
bv --robot-recipes

Historical Analysis

# Compare to historical point
bv --diff-since HEAD~10 --robot-diff
bv --diff-since v1.0.0 --robot-diff
bv --diff-since 2025-11-01 --robot-diff

# View historical state
bv --as-of v1.0.0 --robot-insights

Drift Detection

# Save baseline for future comparison
bv --save-baseline "Q4 2025 baseline - pre-refactoring"

# Check for architectural drift
bv --check-drift --robot-drift

# View baseline metadata
bv --baseline-info

Multi-Repository Support

# Aggregate multiple repositories
bv --workspace .bv/workspace.yaml --robot-insights

# Filter by repository
bv --workspace .bv/workspace.yaml --repo api --robot-plan

Decision-Making Framework

Priority Matrix

Use metric combinations to make intelligent recommendations:

Scenario	Metrics	Action
Critical Bottleneck	High PageRank + High Betweenness + High Critical Path	HIGHEST PRIORITY - blocks everything
Foundational Work	High PageRank + High Authority + Low Out-Degree	HIGH PRIORITY - enables downstream work
Integration Point	High Hub + High Betweenness	COORDINATE - needs many inputs
Quick Win	Low Degree + No dependencies	PARALLELIZABLE - good for side work
Architectural Debt	Part of cycle + High density	REFACTOR - break dependencies
Isolated Feature	Low all metrics + Degree = 0	INDEPENDENT - work anytime

Health Indicators

Healthy Project:

{
  "density": 0.2-0.4,
  "cycles": [],
  "topologicalSortValid": true,
  "healthTrend": "stable"
}

Warning Signs:

{
  "density": 0.6-0.8,
  "cycles": [1-3],
  "highBetweennessConcentration": ">5 issues with score >0.8"
}

Critical Issues:

{
  "density": ">0.8",
  "cycles": "4+",
  "topologicalSortValid": false
}

Common Workflows

1. Initial Project Assessment

# Get comprehensive analysis
bv --robot-insights > insights.json

# Generate execution plan
bv --robot-plan > plan.json

# Check priority alignment
bv --robot-priority > priority.json

# Export human-readable report
bv --export-md health-report.md

Decision Logic:

const insights = JSON.parse(fs.readFileSync('insights.json'));

if (insights.cycles.length > 0) {
  return "CRITICAL: Break cycles before other work";
} else if (insights.graphStats.density.density > 0.7) {
  return "WARNING: Over-coupled - recommend modularization";
} else {
  return `HEALTHY: Focus on ${plan.summary.recommendedNextIssue}`;
}

2. Sprint Planning

# Filter actionable issues (no blockers)
bv --recipe actionable --robot-plan > sprint-plan.json

# Get high-impact recommendations
bv --robot-insights | jq '.recommendations.highImpactIssues'

# Verify priorities
bv --robot-priority | jq '.recommendations[] | select(.confidence > 0.8)'

Team Allocation:

Senior engineers: High impact (impactScore > 0.7)
Mid-level engineers: Unblocking work (unblocks.length > 0)
Junior engineers: Quick wins (no dependencies, low impact)

3. Architectural Refactoring

# Save baseline before refactoring
bv --save-baseline "Pre-refactoring baseline - $(date +%Y-%m-%d)"

# Identify refactoring targets
bv --robot-insights > current.json

# Prioritize by:
# 1. Break cycles (highest priority)
# 2. Extract bottlenecks (high betweenness)
# 3. Reduce coupling (high density)
# 4. Stabilize foundations (high PageRank)

4. CI/CD Health Monitoring

# .github/workflows/architecture-health.yml
- name: Check drift
  run: bv --check-drift --robot-drift > drift-report.json

- name: Analyze results
  run: |
    EXIT_CODE=$(jq -r '.exitCode' drift-report.json)
    if [ "$EXIT_CODE" == "1" ]; then
      echo "::error::Critical drift - new cycles detected"
      exit 1
    elif [ "$EXIT_CODE" == "2" ]; then
      echo "::warning::Metrics degraded - review recommended"
    fi

Exit Codes:

0 = Healthy (no drift)
1 = Critical (new cycles)
2 = Warning (density increase, more blocked issues)

5. Historical Analysis

# Compare to last release
bv --diff-since v1.0.0 --robot-diff > release-diff.json

# Check health trend
jq -r '.summary.healthTrend' release-diff.json
# Output: 'improving', 'degrading', or 'stable'

# View resolved cycles
jq '.changes.resolvedCycles' release-diff.json

TypeScript Integration

import {
  InsightsResponse,
  PlanResponse,
  PriorityResponse,
  DiffResponse,
  DriftResponse
} from '../bv-codebase/types/core';

// Example: Check project health
async function checkProjectHealth(): Promise<void> {
  const { stdout } = await execAsync('bv --robot-insights');
  const insights: InsightsResponse = JSON.parse(stdout);

  const healthScore = calculateHealthScore(insights);

  if (healthScore < 60) {
    console.log('❌ CRITICAL: Immediate action required');
    console.log(`Cycles: ${insights.cycles.length}`);
    console.log(`Density: ${insights.graphStats.density.interpretation}`);
  } else if (healthScore < 80) {
    console.log('⚠️  WARNING: Architectural improvements recommended');
  } else {
    console.log('✅ HEALTHY: Project in good state');
  }
}

function calculateHealthScore(insights: InsightsResponse): number {
  let score = 100;

  // Deduct for cycles
  score -= insights.cycles.length * 15;

  // Deduct for high density
  if (insights.graphStats.density.density > 0.7) score -= 20;
  else if (insights.graphStats.density.density > 0.5) score -= 10;

  // Deduct for bottlenecks
  const bottlenecks = insights.metrics.betweenness.filter(m => m.score > 0.7);
  score -= bottlenecks.length * 5;

  return Math.max(0, score);
}

Multi-Repository Support

Workspace Configuration

# .bv/workspace.yaml
repos:
  - name: core-api
    path: ../core-api
    prefix: api-

  - name: web-frontend
    path: ../web-frontend
    prefix: web-

  - name: mobile-app
    path: ../mobile-app
    prefix: mobile-

Usage

# View all repositories together
bv --workspace .bv/workspace.yaml --robot-insights

# Filter by repository prefix
bv --workspace .bv/workspace.yaml --repo api --robot-plan

# Identify cross-repo dependencies (high betweenness)
bv --workspace .bv/workspace.yaml --robot-insights | \
  jq '.metrics.betweenness[] | select(.score > 0.7)'

Namespaced Issue IDs: api-issue-001, web-issue-002, mobile-issue-003

Hook System

Configuration (`.bv/hooks.yaml`)

preExport:
  - name: validate
    command: ./scripts/validate-before-export.sh
    failOn: error

postExport:
  - name: notify-slack
    command: ./scripts/send-slack-notification.sh
    env:
      SLACK_WEBHOOK: $SLACK_WEBHOOK_URL
    failOn: never

  - name: upload-report
    command: ./scripts/upload-to-s3.sh
    failOn: never

Environment Variables

Available in hook scripts:

BV_EXPORT_PATH - Output file path
BV_EXPORT_FORMAT - markdown or json
BV_ISSUE_COUNT - Total issues
BV_TIMESTAMP - Export timestamp

Skip Hooks

bv --export-md report.md --no-hooks

Performance Optimization

Automatic Metric Skipping

Small graphs (< 100 nodes): All 9 metrics computed (~1s)
Medium graphs (100-1000 nodes): Skip betweenness unless needed (~2-5s)
Large graphs (> 1000 nodes): Essential metrics only (~5-10s)

Force Full Analysis

bv --force-full-analysis --robot-insights

Use when: Comprehensive audit required (may take 30s+ for large graphs)

Profiling

# Human-readable
bv --profile-startup

# JSON for monitoring systems
bv --profile-startup --profile-json

Error Handling

All robot commands return valid JSON even on error:

{
  "error": true,
  "message": "No baseline found. Run --save-baseline first.",
  "code": "NO_BASELINE",
  "suggestion": "bv --save-baseline \"Initial baseline\""
}

Always parse JSON safely:

try {
  const result = JSON.parse(stdout) as InsightsResponse;
  // Process result
} catch (error) {
  console.error('Failed to parse bv output:', error);
}

Best Practices

✅ DO

Always use --robot-* flags - never launch the TUI
Parse JSON output - structured data for programmatic decisions
Check exit codes in CI - 0 = success, 1 = critical, 2 = warning
Save baselines before major changes - enables drift detection
Combine commands for rich analysis - layer insights for better decisions
Use recipes for filtering - --recipe actionable for sprint planning
Track metrics over time - use --diff-since for trends

❌ DON'T

Never run bv without robot flags - will block indefinitely in TUI
Don't ignore cycles - circular dependencies must be resolved
Don't skip drift checks in CI - prevents architectural degradation
Don't force full analysis unnecessarily - slow for large graphs
Don't parse human-readable output - always use JSON from robot commands
Don't create baselines without descriptions - context is critical

Quick Reference

Command Cheatsheet

# Analysis
bv --robot-insights                           # Full metrics
bv --robot-plan                               # Execution plan
bv --robot-priority                           # Priority recommendations
bv --robot-recipes                            # Available recipes

# Historical
bv --diff-since HEAD~10 --robot-diff          # Compare to 10 commits ago
bv --diff-since v1.0.0 --robot-diff           # Compare to release tag
bv --diff-since 2025-11-01 --robot-diff       # Compare to date
bv --as-of v1.0.0 --robot-insights            # View historical state

# Drift Detection
bv --save-baseline "description"              # Save current metrics
bv --check-drift --robot-drift                # Check for drift
bv --baseline-info                            # View baseline metadata

# Multi-Repo
bv --workspace .bv/workspace.yaml --robot-insights    # All repos
bv --workspace .bv/workspace.yaml --repo api --robot-plan  # Filter by repo

# Filtering
bv --recipe actionable --robot-plan           # No blockers
bv --recipe high-impact --robot-insights      # High metrics
bv --recipe blocked --robot-insights          # Issues with blockers

# Export
bv --export-md report.md                      # Markdown report
bv --export-md report.md --no-hooks           # Skip hooks

# Performance
bv --force-full-analysis --robot-insights     # Compute all metrics
bv --profile-startup --profile-json           # Performance profiling

JQ Helpers

# Extract specific data
bv --robot-insights | jq '.recommendations.highImpactIssues'
bv --robot-plan | jq '.summary.recommendedNextIssue'
bv --robot-priority | jq '.recommendations[] | select(.confidence > 0.8)'

# Filter by metrics
bv --robot-insights | jq '.metrics.pageRank[] | select(.score > 0.7)'
bv --robot-insights | jq '.metrics.betweenness[] | select(.score > 0.8)'

# Check health
bv --robot-insights | jq '.cycles | length'
bv --robot-insights | jq '.graphStats.density.interpretation'
bv --check-drift --robot-drift | jq '.exitCode'

Files & Resources

Skill Files

SKILL.md - This file
scripts/metrics-validator.sh - Validate metrics output
references/robot-commands.md - Complete command reference
references/graph-analysis.md - Metric interpretation guide
assets/cheatsheet.md - Quick command reference

Codebase Files

../bv-codebase/types/core.ts - TypeScript type definitions
../bv-codebase/principles/graph-metrics.md - Deep dive into metrics
../bv-codebase/principles/robot-protocol.md - Protocol documentation
../bv-codebase/templates/analysis-workflow.md - Common patterns
../bv-codebase/README.md - Codebase overview

Installation

# macOS (Homebrew)
brew install beadslabs/tap/bv

# Linux
curl -L https://github.com/beadslabs/bv/releases/latest/download/bv-linux-amd64 -o bv
chmod +x bv
sudo mv bv /usr/local/bin/

# Verify
bv --version

Troubleshooting

Issue: bv hangs forever

Cause: TUI launched without robot flag
Fix: Always use --robot-* flags

Issue: Empty JSON response

Cause: No issues in .beads/ directory
Fix: Verify tracker exists

Issue: Metrics missing in output

Cause: Large graph, automatic skipping
Fix: Use --force-full-analysis

Issue: Drift check always returns 0

Cause: No baseline saved
Fix: Run bv --save-baseline "Initial baseline" first

Examples

Example 1: Sprint Planning

#!/bin/bash
# Generate sprint plan

# 1. Get actionable issues
bv --recipe actionable --robot-plan > sprint-plan.json

# 2. Extract high-impact work
HIGH_IMPACT=$(jq -r '.tracks[].items[] | select(.impactScore > 0.7) | .issueId' sprint-plan.json)

# 3. Extract quick wins
QUICK_WINS=$(jq -r '.tracks[].items[] | select(.dependencies | length == 0) | select(.unblocks | length == 0) | .issueId' sprint-plan.json)

echo "High Impact Issues:"
echo "$HIGH_IMPACT"
echo ""
echo "Quick Wins:"
echo "$QUICK_WINS"

Example 2: CI Health Check

#!/bin/bash
# CI pipeline drift check

bv --check-drift --robot-drift > drift-report.json
EXIT_CODE=$?

if [ $EXIT_CODE -eq 1 ]; then
  echo "❌ CRITICAL: New cycles detected"
  jq -r '.alerts[] | select(.level == "critical") | .message' drift-report.json
  exit 1
elif [ $EXIT_CODE -eq 2 ]; then
  echo "⚠️  WARNING: Metrics degraded"
  jq -r '.alerts[] | select(.level == "warning") | .message' drift-report.json
  exit 0
else
  echo "✅ HEALTHY: No drift detected"
  exit 0
fi

Example 3: Priority Validation

#!/bin/bash
# Check for priority misalignments

bv --robot-priority > priority-check.json

HIGH_CONFIDENCE=$(jq '.recommendations[] | select(.confidence > 0.8)' priority-check.json)

if [ -n "$HIGH_CONFIDENCE" ]; then
  echo "⚠️  High-confidence priority adjustments recommended:"
  echo "$HIGH_CONFIDENCE" | jq -r '"\(.issueId): P\(.currentPriority) → P\(.recommendedPriority) (\(.reasoning))"'
else
  echo "✅ Priorities are well-aligned with metrics"
fi

Version Compatibility

bv: v1.0.0+
Robot Protocol: v1.x (semver-stable)
This Skill: v1.0.0

License

This skill documentation is provided for AI agents and developers.

bv is developed by Beads Labs. See https://github.com/beadslabs/bv for tool licensing.

bv

bv Skill: AI-Driven Issue Tracker Analysis

Overview

When to Use This Skill

Task Prioritization

Dependency Analysis

Project Health Monitoring

Architectural Refactoring

Historical Analysis

Core Capabilities

1. Graph Metrics (9 Dimensions)

2. Robot Protocol Commands

Analysis Commands

Historical Analysis

Drift Detection

Multi-Repository Support

Decision-Making Framework

Priority Matrix

Health Indicators

Common Workflows

1. Initial Project Assessment

2. Sprint Planning

3. Architectural Refactoring

4. CI/CD Health Monitoring

5. Historical Analysis

TypeScript Integration

Multi-Repository Support

Workspace Configuration

Usage

Hook System

Configuration (.bv/hooks.yaml)

Environment Variables

Skip Hooks

Performance Optimization

Automatic Metric Skipping

Force Full Analysis

Profiling

Error Handling

Best Practices

✅ DO

❌ DON'T

Quick Reference

Command Cheatsheet

JQ Helpers

Files & Resources

Skill Files

Codebase Files

Installation

Troubleshooting

Examples

Example 1: Sprint Planning

Example 2: CI Health Check

Example 3: Priority Validation

Version Compatibility

License

Configuration (`.bv/hooks.yaml`)