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 enhance project oversight by monitoring development speed and efficiency. It automates the calculation of key performance indicators such as cycle times and story point velocity, helping Project Managers identify trends, detect stalled tasks (99% rule violations), and make informed decisions based on historical performance metrics.
Use Cases
- Performance Benchmarking: Automatically calculate and compare current development velocity against historical averages after completing task groups.
- Bottleneck Identification: Detect tasks that are stuck or taking disproportionately longer than estimated to prevent project delays.
- Resource Planning: Evaluate current team capacity and velocity trends before spawning new developers or starting new project iterations.
- Strategic Reporting: Generate comprehensive project metrics reports including cycle times and trend analysis for stakeholder reviews and retrospectives.
| 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