370 lines
8.9 KiB
Markdown
370 lines
8.9 KiB
Markdown
---
|
||
description: velocity
|
||
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
|
||
---
|
||
|
||
# velocity
|
||
|
||
Track team velocity, calculate trends, and forecast completion dates.
|
||
|
||
## Prompt
|
||
|
||
ROLE: Velocity Analyst & Forecaster
|
||
|
||
OBJECTIVE
|
||
Calculate team velocity from completed stories, identify trends, and forecast epic/milestone completion dates.
|
||
|
||
INPUTS (optional)
|
||
- PERIOD=week|sprint|month|all (default: sprint - last 2 weeks)
|
||
- FORECAST=<EPIC_ID or milestone> (predict completion date)
|
||
- FORMAT=report|chart|json (default: report)
|
||
|
||
DATA SOURCES
|
||
|
||
1. **Story Completion Data**
|
||
- docs/09-agents/status.json (current state)
|
||
- docs/09-agents/bus/log.jsonl (historical status changes)
|
||
- docs/06-stories/**/US-*.md (story estimates and metadata)
|
||
|
||
2. **Epic/Milestone Data**
|
||
- docs/05-epics/*.md (epic definitions)
|
||
- docs/08-project/milestones.md (milestone targets)
|
||
|
||
VELOCITY CALCULATION
|
||
|
||
### Story Points Completed
|
||
Parse bus/log.jsonl for status changes to "done":
|
||
```json
|
||
{"ts":"2025-10-10T10:00:00Z","type":"status","story":"US-0030","status":"done"}
|
||
{"ts":"2025-10-11T14:30:00Z","type":"status","story":"US-0031","status":"done"}
|
||
```
|
||
|
||
For each story, get estimate from story file frontmatter:
|
||
```yaml
|
||
estimate: 1.5d
|
||
```
|
||
|
||
Convert to points (1d = 1 point) and sum by time period.
|
||
|
||
### Velocity Calculation
|
||
```
|
||
Velocity = Total points completed / Number of time periods
|
||
```
|
||
|
||
Example:
|
||
- Week 1: 8 points
|
||
- Week 2: 10 points
|
||
- Week 3: 7 points
|
||
- **Average velocity**: (8+10+7)/3 = **8.3 points/week**
|
||
|
||
VELOCITY REPORT
|
||
|
||
```markdown
|
||
# Velocity Report
|
||
|
||
**Generated**: 2025-10-17 14:30
|
||
**Period**: Last 4 sprints (8 weeks)
|
||
**Team**: AG-UI, AG-API, AG-CI, AG-DEVOPS
|
||
|
||
---
|
||
|
||
## 📊 Current Velocity
|
||
|
||
**Average**: 8.3 points/week
|
||
**Trend**: ↗️ +15% (improving)
|
||
**Last sprint**: 10 points
|
||
**Best sprint**: 12 points (Week of 2025-09-15)
|
||
**Worst sprint**: 5 points (Week of 2025-09-01)
|
||
|
||
---
|
||
|
||
## 📈 Historical Velocity
|
||
|
||
```
|
||
Points
|
||
12 │ ●
|
||
11 │ ╱
|
||
10 │ ● ● ●
|
||
9 │ ╱ ╲ ╱
|
||
8 │ ● ●
|
||
7 │ ●
|
||
6 │ ╱
|
||
5 │ ● ●
|
||
4 │ ╱
|
||
3 │
|
||
└────────────────────
|
||
W1 W2 W3 W4 W5 W6 W7 W8
|
||
|
||
Trend line: ─── (moving average)
|
||
Actual: ● ─ ●
|
||
```
|
||
|
||
**Weekly Breakdown**:
|
||
| Week | Points | Stories | Avg Size | Notes |
|
||
|------|--------|---------|----------|-------|
|
||
| 2025-10-14 | 10 | 6 | 1.7d | ↗️ +25% |
|
||
| 2025-10-07 | 8 | 5 | 1.6d | ↗️ +14% |
|
||
| 2025-09-30 | 7 | 4 | 1.8d | ↘️ -30% |
|
||
| 2025-09-23 | 10 | 7 | 1.4d | ↗️ +100% |
|
||
| 2025-09-16 | 5 | 3 | 1.7d | ↘️ -50% |
|
||
| 2025-09-09 | 10 | 6 | 1.7d | - |
|
||
|
||
**Insights**:
|
||
- Velocity is trending upward (+15% over 6 weeks)
|
||
- Best performance when story size ≤1.5d
|
||
- Week of 2025-09-23 had highest throughput (7 stories)
|
||
- Consistency improving (std dev: 2.1 → 1.8)
|
||
|
||
---
|
||
|
||
## 👥 Velocity by Owner
|
||
|
||
| Owner | Points/Week | Stories/Week | Utilization | Trend |
|
||
|-------|-------------|--------------|-------------|-------|
|
||
| AG-UI | 3.2 | 2.1 | 80% | ↗️ +10% |
|
||
| AG-API | 4.1 | 2.8 | 85% | ↗️ +20% |
|
||
| AG-CI | 0.8 | 0.6 | 40% | → Stable |
|
||
| AG-DEVOPS | 0.2 | 0.2 | 10% | 🆕 New |
|
||
|
||
**Observations**:
|
||
- AG-API is the team workhorse (4.1 pts/wk)
|
||
- AG-CI underutilized (consider more stories)
|
||
- AG-DEVOPS just started (too early for trends)
|
||
|
||
---
|
||
|
||
## 🎯 Forecast: Epic Completion
|
||
|
||
### EP-0010: User Authentication
|
||
- **Stories**: 12 total
|
||
- **Completed**: 8 (66%)
|
||
- **Remaining**: 4 stories, 6 points
|
||
- **At current velocity** (8.3 pts/wk): **< 1 week**
|
||
- **Forecast completion**: **2025-10-24** (7 days)
|
||
- **Confidence**: High (85%)
|
||
|
||
### EP-0011: Payment Integration
|
||
- **Stories**: 8 total
|
||
- **Completed**: 2 (25%)
|
||
- **Remaining**: 6 stories, 9 points
|
||
- **At current velocity** (8.3 pts/wk): **~1.1 weeks**
|
||
- **Forecast completion**: **2025-10-28** (11 days)
|
||
- **Confidence**: Medium (70%)
|
||
|
||
### Milestone: Public Beta Launch
|
||
- **Target date**: 2025-11-15
|
||
- **Total remaining**: 15 stories, 24 points
|
||
- **Weeks needed**: 24/8.3 = **2.9 weeks**
|
||
- **Forecast completion**: **2025-11-07** (21 days)
|
||
- **Status**: ✅ **On track** (8 days buffer)
|
||
- **Risk level**: Low
|
||
|
||
---
|
||
|
||
## ⚠️ Risk Analysis
|
||
|
||
### Velocity Risks
|
||
1. **AG-API dependency**: 50% of points from one agent
|
||
- *Mitigation*: Cross-train, pair programming
|
||
2. **Story size variance**: Some 2d stories slow velocity
|
||
- *Mitigation*: Split stories >1.5d
|
||
3. **Seasonal slowdown**: Historical dip in Week 5
|
||
- *Mitigation*: Add buffer to forecasts
|
||
|
||
### Schedule Risks
|
||
- EP-0011 blocking Milestone: Public Beta
|
||
- If velocity drops 20% → Beta delayed to 2025-11-12
|
||
- If AG-API unavailable → 50% velocity loss
|
||
|
||
---
|
||
|
||
## 📅 Capacity Planning
|
||
|
||
**Current Capacity**: 8.3 points/week (4 agents)
|
||
|
||
**Recommendations**:
|
||
1. **This Sprint** (2 weeks):
|
||
- Plan: 16-18 points (2x velocity)
|
||
- Buffer: Keep 2-3 ready stories
|
||
- Focus: Complete EP-0010
|
||
|
||
2. **Next Sprint**:
|
||
- Plan: 16-20 points
|
||
- Priority: EP-0011 (Beta blocker)
|
||
- Consider: Add stories for AG-CI (underutilized)
|
||
|
||
3. **Long-term**:
|
||
- Maintain 8-10 points/week sustained velocity
|
||
- Reserve 20% for tech debt (/AgileFlow:tech-debt command)
|
||
- Keep story sizes ≤1.5d for predictability
|
||
|
||
---
|
||
|
||
## 🎯 Velocity Goals
|
||
|
||
**Current**: 8.3 points/week
|
||
**Target**: 10 points/week (by end of quarter)
|
||
**Stretch**: 12 points/week
|
||
|
||
**Action Items**:
|
||
- [ ] Split 2 large stories (US-0050, US-0051)
|
||
- [ ] Assign 2 more stories to AG-CI
|
||
- [ ] Review blockers (US-0041)
|
||
- [ ] Celebrate hitting 10 pts/wk milestone! 🎉
|
||
|
||
---
|
||
|
||
## 📊 Export Options
|
||
|
||
Save this report?
|
||
- `docs/08-project/velocity/velocity-2025-10-17.md`
|
||
- Update velocity dashboard
|
||
- Add to stakeholder update
|
||
```
|
||
|
||
FORECASTING ALGORITHM
|
||
|
||
### Simple Linear Forecast
|
||
```
|
||
Days to complete = (Remaining points / Velocity) * 7
|
||
Completion date = Today + Days to complete
|
||
```
|
||
|
||
### Confidence Calculation
|
||
```
|
||
Confidence = 100% - (Velocity std dev / Velocity avg) * 100
|
||
|
||
High confidence: >80% (stable velocity)
|
||
Medium: 60-80% (some variance)
|
||
Low: <60% (high variance, unreliable)
|
||
```
|
||
|
||
### Monte Carlo Simulation (optional, advanced)
|
||
Run 1000 simulations with velocity variance:
|
||
```
|
||
For each simulation:
|
||
- Sample velocity from normal distribution (mean, std dev)
|
||
- Calculate completion date
|
||
- Record result
|
||
|
||
Forecast:
|
||
- P50 (median): 50% chance of completing by this date
|
||
- P80: 80% chance
|
||
- P90: 90% chance (conservative estimate)
|
||
```
|
||
|
||
VELOCITY CHART (ASCII Art)
|
||
|
||
```
|
||
Velocity Trend (8 weeks)
|
||
|
||
Points/Week
|
||
12 ┤ ●●●
|
||
11 ┤ ●
|
||
10 ┤ ●● ●
|
||
9 ┤ ● ●
|
||
8 ┤ ● ← Current (8.3 avg)
|
||
7 ┤ ●
|
||
6 ┤ ●
|
||
5 ┤ ● ●
|
||
4 ┤ ●
|
||
3 ┤
|
||
└─────────────────────────────────────
|
||
W1 W2 W3 W4 W5 W6 W7 W8
|
||
|
||
Legend:
|
||
● Actual velocity
|
||
─ Trend line (moving average)
|
||
↗️ Trend: +15% over period
|
||
```
|
||
|
||
VELOCITY BY STORY SIZE
|
||
|
||
```
|
||
Velocity by Story Size
|
||
|
||
Size | Count | Avg Days | Success Rate
|
||
--------|-------|----------|-------------
|
||
≤0.5d | 8 | 0.4d | 100% ✅
|
||
0.5-1d | 12 | 0.9d | 92% ✅
|
||
1-1.5d | 10 | 1.3d | 80% ⚠️
|
||
1.5-2d | 6 | 2.1d | 67% ⚠️
|
||
>2d | 3 | 3.5d | 33% 🔴
|
||
|
||
**Insight**: Stories ≤1d complete faster and more reliably.
|
||
**Recommendation**: Split stories >1.5d into smaller increments.
|
||
```
|
||
|
||
JSON OUTPUT (for tooling)
|
||
|
||
```json
|
||
{
|
||
"generated": "2025-10-17T14:30:00Z",
|
||
"period": "8 weeks",
|
||
"velocity": {
|
||
"current": 8.3,
|
||
"trend": "+15%",
|
||
"last_sprint": 10,
|
||
"best": 12,
|
||
"worst": 5,
|
||
"std_dev": 2.1
|
||
},
|
||
"by_owner": {
|
||
"AG-UI": 3.2,
|
||
"AG-API": 4.1,
|
||
"AG-CI": 0.8,
|
||
"AG-DEVOPS": 0.2
|
||
},
|
||
"forecasts": [
|
||
{
|
||
"epic": "EP-0010",
|
||
"remaining_points": 6,
|
||
"weeks_needed": 0.7,
|
||
"completion_date": "2025-10-24",
|
||
"confidence": 85
|
||
}
|
||
],
|
||
"risks": [
|
||
{
|
||
"type": "dependency",
|
||
"description": "50% of points from AG-API",
|
||
"severity": "medium"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
WORKFLOW
|
||
|
||
1. Parse bus/log.jsonl for "done" status changes
|
||
2. Match stories to estimates from frontmatter
|
||
3. Group completions by time period (week/sprint)
|
||
4. Calculate velocity stats (avg, trend, std dev)
|
||
5. If FORECAST specified:
|
||
- Calculate remaining points
|
||
- Apply velocity to forecast completion
|
||
- Calculate confidence level
|
||
6. Render report/chart
|
||
7. Suggest actions based on findings
|
||
|
||
INTEGRATION
|
||
|
||
- Save velocity history to docs/08-project/velocity/
|
||
- Update /AgileFlow:stakeholder-update with velocity data
|
||
- Alert if velocity drops >20% from average
|
||
- Suggest sprint planning capacity based on velocity
|
||
|
||
RULES
|
||
- Always calculate over at least 3 time periods (for reliability)
|
||
- Warn if sample size too small (<5 stories)
|
||
- Exclude outliers (stories >3x avg) from velocity calc
|
||
- Account for holidays/time off in forecasts
|
||
- Update forecast confidence based on variance
|
||
|
||
OUTPUT
|
||
- Velocity report (markdown/chart/json)
|
||
- Trend analysis
|
||
- Forecasts for epics/milestones
|
||
- Risk analysis
|
||
- Action items
|