Initial commit
This commit is contained in:
Zhongwei Li
369
commands/velocity.md
Normal file
369
commands/velocity.md
Normal file
@@ -0,0 +1,369 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user