velocity-tracker

mehdic's avatarfrom mehdic

Track development velocity, cycle times, and identify trends for PM decision-making

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

The Velocity Tracker skill is a data-driven analytical tool designed to optimize software development workflows. It automatically calculates key performance indicators such as development velocity and cycle times by analyzing project databases. By identifying trends and detecting '99% rule' violations (tasks that appear nearly finished but are stalled), it provides Project Managers with actionable insights and quantitative metrics to improve decision-making, resource allocation, and sprint predictability.

Use Cases

  • Post-Task Analysis: Automatically calculate cycle times after completing a group of tasks to evaluate team efficiency.
  • Capacity Planning: Check current velocity trends before onboarding new developers to determine if the team has the capacity for more parallel work.
  • Bottleneck Detection: Identify tasks that are stuck or violating the '99% rule' to escalate issues to technical leads before they impact deadlines.
  • Iteration Planning: Use historical performance data and trend analysis to create more accurate estimates for future development cycles.
  • Performance Reporting: Generate comprehensive JSON reports and summaries that compare current progress against historical averages for stakeholder updates.
namevelocity-tracker
descriptionTrack development velocity, cycle times, and identify trends for PM decision-making
version1.0.0
allowed-tools[Bash, Read]

Velocity Tracker Skill

You are the velocity-tracker skill. When invoked, you analyze historical project data to provide quantitative metrics for PM decision-making.

When to Invoke This Skill

Invoke this skill when:

  • After completing each task group (to track cycle time)
  • Before spawning new developers (to check velocity capacity)
  • When a task appears stuck (to detect 99% rule violations)
  • Before sending BAZINGA (to record final metrics for learning)
  • Planning next iteration (to use historical data)

Do NOT invoke when:

  • First run with no completed tasks yet
  • Emergency bug fixes (skip metrics to save time)
  • User explicitly requests fast mode
  • No PM state file exists yet

Your Task

When invoked:

  1. Execute the velocity tracking script
  2. Read the generated metrics report
  3. Return a summary to the calling agent

Step 1: Execute Velocity Tracking Script

Use the Bash tool to run the pre-built tracking script.

On Unix/macOS:

bash .claude/skills/velocity-tracker/scripts/track.sh

On Windows (PowerShell):

pwsh .claude/skills/velocity-tracker/scripts/track.ps1

Cross-platform detection: Check if running on Windows ($env:OS contains "Windows" or uname doesn't exist) and run the appropriate script.

This script will:

  • Read PM state from database (bazinga/bazinga.db)
  • Calculate current velocity and cycle times
  • Compare against historical metrics
  • Detect trends (improving/stable/declining)
  • Identify 99% rule violations
  • Generate bazinga/artifacts/{SESSION_ID}/skills/project_metrics.json
  • Update bazinga/artifacts/{SESSION_ID}/skills/historical_metrics.json

Step 2: Read Generated Report

Use the Read tool to read the generated report:

bazinga/artifacts/{SESSION_ID}/skills/project_metrics.json

Extract key information:

  • current_run.velocity - Story points completed
  • current_run.percent_complete - Progress percentage
  • trends.velocity - Velocity trend
  • warnings - Any 99% rule violations
  • recommendations - Action items

Step 3: Return Summary

Return a concise summary to the calling agent:

Velocity Metrics:
- Current velocity: {velocity} story points (historical avg: {historical_avg})
- Trend: {improving/stable/declining}
- Cycle time: {avg_minutes} minutes average
- Completion: {percent}%

{If warnings exist:}
⚠️  Warnings:
- {warning 1}
- {warning 2}

Top Recommendations:
1. {recommendation 1}
2. {recommendation 2}
3. {recommendation 3}

Details saved to: bazinga/artifacts/{SESSION_ID}/skills/project_metrics.json

Example Invocation

Scenario 1: Normal Progress Check

Input: PM agent requests velocity check after completing task group G002

Expected output:

Velocity Metrics:
- Current velocity: 12 story points (historical avg: 10.5)
- Trend: improving
- Cycle time: 45 minutes average
- Completion: 40%

Top Recommendations:
1. Current velocity exceeds historical average - good progress
2. Estimated remaining time: 3.5 hours

Details saved to: bazinga/artifacts/{SESSION_ID}/skills/project_metrics.json

Scenario 2: 99% Rule Violation Detected

Input: PM agent checks why task G003 is taking too long

Expected output:

Velocity Metrics:
- Current velocity: 8 story points (historical avg: 10.5)
- Trend: declining
- Cycle time: 125 minutes average
- Completion: 30%

⚠️  Warnings:
- 99% Rule Violation: Task G003 taking 3x longer than expected (135 min vs 45 min estimate)

Top Recommendations:
1. Escalate G003 to Tech Lead for investigation
2. Velocity below average - may need task breakdown
3. Database tasks pattern: taking 2.5x estimate

Details saved to: bazinga/artifacts/{SESSION_ID}/skills/project_metrics.json

Error Handling

If script fails:

  • Check the script output for error messages
  • Verify database bazinga/bazinga.db exists and contains PM state
  • Return error message to calling agent

If no completed groups:

  • Return: "No completed groups yet. Run velocity tracker after completing at least one task group."

If historical data missing:

  • Script will create initial baseline
  • Note: "First run - no historical comparison available"

Notes

  • The script handles all calculation logic (260+ lines)
  • Supports both bash (Linux/Mac) and PowerShell (Windows)
  • Gracefully degrades if historical data is missing
  • Automatically updates historical metrics for future runs