velocity-tracker
Track development velocity, cycle times, and identify trends for PM decision-making
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.
| name | velocity-tracker |
|---|---|
| description | Track development velocity, cycle times, and identify trends for PM decision-making |
| version | 1.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:
- Execute the velocity tracking script
- Read the generated metrics report
- 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:OScontains "Windows" orunamedoesn'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 completedcurrent_run.percent_complete- Progress percentagetrends.velocity- Velocity trendwarnings- Any 99% rule violationsrecommendations- 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.dbexists 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