Initial commit
This commit is contained in:
Zhongwei Li
584
commands/story-metrics.md
Normal file
584
commands/story-metrics.md
Normal file
@@ -0,0 +1,584 @@
|
||||
# /sdd:story-metrics
|
||||
|
||||
## Meta
|
||||
- Version: 2.0
|
||||
- Category: story-analysis
|
||||
- Complexity: medium
|
||||
- Purpose: Calculate and display development velocity, cycle time, and quality metrics from story data
|
||||
|
||||
## Definition
|
||||
**Purpose**: Analyze completed and in-progress stories to understand development patterns, velocity trends, bottlenecks, and generate actionable insights.
|
||||
|
||||
**Syntax**: `/sdd:story-metrics [period]`
|
||||
|
||||
## Parameters
|
||||
| Parameter | Type | Required | Default | Description | Validation |
|
||||
|-----------|------|----------|---------|-------------|------------|
|
||||
| period | string | No | "all" | Time period to analyze (week, month, quarter, all) | One of: week, month, quarter, all |
|
||||
|
||||
## INSTRUCTION: Analyze Story Metrics
|
||||
|
||||
### INPUTS
|
||||
- period: Optional time period filter (defaults to all-time)
|
||||
- Story files from all directories:
|
||||
- `/docs/stories/backlog/` - Stories not started
|
||||
- `/docs/stories/development/` - Active stories
|
||||
- `/docs/stories/review/` - Stories in review
|
||||
- `/docs/stories/qa/` - Stories in testing
|
||||
- `/docs/stories/completed/` - Finished stories
|
||||
|
||||
### PROCESS
|
||||
|
||||
#### Phase 1: Data Collection
|
||||
1. **SCAN** all story directories for `.md` files
|
||||
2. **PARSE** each story file to extract:
|
||||
- Story ID and title
|
||||
- Status (current folder)
|
||||
- Started date
|
||||
- Completed date
|
||||
- Stage transitions (from progress log)
|
||||
- Test results
|
||||
- Bug count (from progress log)
|
||||
- Story size (days to complete)
|
||||
- Technologies used (from technical notes)
|
||||
|
||||
3. **FILTER** by period if specified:
|
||||
- week: Last 7 days
|
||||
- month: Last 30 days
|
||||
- quarter: Last 90 days
|
||||
- all: All stories
|
||||
|
||||
4. **CALCULATE** time in each stage:
|
||||
- Development time
|
||||
- Review time
|
||||
- QA time
|
||||
- Total cycle time
|
||||
|
||||
#### Phase 2: Velocity Metrics
|
||||
1. **COUNT** completed stories per time period
|
||||
2. **CALCULATE** average cycle time (start to completion)
|
||||
3. **COMPUTE** throughput (stories per week)
|
||||
4. **GENERATE** trend analysis:
|
||||
- Group stories by week
|
||||
- Create visual bar chart
|
||||
- Calculate trend direction
|
||||
|
||||
5. **DISPLAY** velocity metrics:
|
||||
```
|
||||
📈 VELOCITY METRICS
|
||||
══════════════════════════════════
|
||||
|
||||
Current Period: [Date range]
|
||||
- Stories completed: [count]
|
||||
- Average cycle time: [X] days
|
||||
- Throughput: [X] stories/week
|
||||
|
||||
Trend (Last 4 Weeks):
|
||||
Week 1: ████████ 8 stories
|
||||
Week 2: ██████ 6 stories
|
||||
Week 3: █████████ 9 stories
|
||||
Week 4: ███████ 7 stories
|
||||
|
||||
Status: [↗ Trending up | ↘ Trending down | → Stable]
|
||||
```
|
||||
|
||||
#### Phase 3: Cycle Time Analysis
|
||||
1. **CALCULATE** average time per stage:
|
||||
- Development: Mean days from start to review
|
||||
- Review: Mean hours from review to QA
|
||||
- QA: Mean hours from QA to completion
|
||||
- Total: Mean days from start to completion
|
||||
|
||||
2. **IDENTIFY** outliers:
|
||||
- Fastest story (min cycle time)
|
||||
- Slowest story (max cycle time)
|
||||
|
||||
3. **DETECT** bottlenecks:
|
||||
- Stage with longest average time
|
||||
- Stage with most variance
|
||||
|
||||
4. **DISPLAY** cycle time analysis:
|
||||
```
|
||||
⏱️ CYCLE TIME ANALYSIS
|
||||
══════════════════════════════════
|
||||
|
||||
Average by Stage:
|
||||
- Development: [X] days
|
||||
- Review: [X] hours
|
||||
- QA: [X] hours
|
||||
- Total: [X] days
|
||||
|
||||
Outliers:
|
||||
- Fastest: [STORY-ID] - [X] days
|
||||
- Slowest: [STORY-ID] - [X] days
|
||||
|
||||
Bottlenecks:
|
||||
- [Stage]: [X]% above average
|
||||
```
|
||||
|
||||
#### Phase 4: Quality Metrics
|
||||
1. **CALCULATE** first-time pass rate:
|
||||
- Stories completed without rework
|
||||
- Percentage of stories passing review first time
|
||||
|
||||
2. **COUNT** bugs by stage:
|
||||
- Average bugs found in review
|
||||
- Average bugs found in QA
|
||||
- Total production incidents
|
||||
|
||||
3. **ANALYZE** test coverage:
|
||||
- Average test cases per story
|
||||
- Percentage with complete test coverage
|
||||
|
||||
4. **COMPUTE** rollback rate:
|
||||
- Stories requiring rollback
|
||||
- Percentage of completed stories
|
||||
|
||||
5. **DISPLAY** quality metrics:
|
||||
```
|
||||
🎯 QUALITY METRICS
|
||||
══════════════════════════════════
|
||||
|
||||
Pass Rate:
|
||||
- First-time pass: [X]%
|
||||
- Average rework cycles: [X]
|
||||
|
||||
Bug Detection:
|
||||
- Avg bugs in review: [X]
|
||||
- Avg bugs in QA: [X]
|
||||
- Production incidents: [count]
|
||||
|
||||
Testing:
|
||||
- Avg test cases: [X]
|
||||
- Coverage target met: [X]%
|
||||
|
||||
Stability:
|
||||
- Rollback rate: [X]%
|
||||
```
|
||||
|
||||
#### Phase 5: Story Size Distribution
|
||||
1. **CATEGORIZE** stories by cycle time:
|
||||
- Small: 1-2 days
|
||||
- Medium: 3-5 days
|
||||
- Large: 5+ days
|
||||
|
||||
2. **CALCULATE** distribution percentages
|
||||
3. **GENERATE** visual distribution chart
|
||||
4. **PROVIDE** sizing recommendation
|
||||
|
||||
5. **DISPLAY** size distribution:
|
||||
```
|
||||
📊 STORY SIZE DISTRIBUTION
|
||||
══════════════════════════════════
|
||||
|
||||
Small (1-2 days): ████████ 40% ([count] stories)
|
||||
Medium (3-5 days): ██████ 30% ([count] stories)
|
||||
Large (5+ days): ██████ 30% ([count] stories)
|
||||
|
||||
Recommendation:
|
||||
[Break down large stories | Continue current sizing | Adjust estimation]
|
||||
```
|
||||
|
||||
#### Phase 6: Technology Usage
|
||||
1. **EXTRACT** technologies from technical notes
|
||||
2. **COUNT** usage frequency across stories
|
||||
3. **IDENTIFY** new technology additions
|
||||
4. **TRACK** adoption dates
|
||||
|
||||
5. **DISPLAY** tech stack usage:
|
||||
```
|
||||
🔧 TECH STACK USAGE
|
||||
══════════════════════════════════
|
||||
|
||||
Most Used:
|
||||
- [Technology]: [X] stories
|
||||
- [Framework]: [X] stories
|
||||
- [Library]: [X] stories
|
||||
|
||||
Recent Additions:
|
||||
- [New Tech]: Added [date]
|
||||
- [New Tool]: Added [date]
|
||||
```
|
||||
|
||||
#### Phase 7: Development Patterns
|
||||
1. **ANALYZE** completion patterns:
|
||||
- Most productive day of week
|
||||
- Most productive time period
|
||||
- Average stories per week
|
||||
|
||||
2. **IDENTIFY** common blockers:
|
||||
- Extract from progress logs
|
||||
- Count blocker frequency
|
||||
- Categorize blocker types
|
||||
|
||||
3. **DISPLAY** development patterns:
|
||||
```
|
||||
📋 DEVELOPMENT PATTERNS
|
||||
══════════════════════════════════
|
||||
|
||||
Productivity:
|
||||
- Most productive day: [Day]
|
||||
- Peak completion time: [Time range]
|
||||
- Avg stories/week: [X]
|
||||
|
||||
Common Blockers:
|
||||
- [Blocker type]: [X] occurrences
|
||||
- [Blocker type]: [X] occurrences
|
||||
```
|
||||
|
||||
#### Phase 8: Predictions
|
||||
1. **CALCULATE** velocity-based projections:
|
||||
- Expected stories next week
|
||||
- Expected stories next month
|
||||
- Confidence interval
|
||||
|
||||
2. **ANALYZE** work-in-progress:
|
||||
- Current parallel stories
|
||||
- Optimal WIP limit based on data
|
||||
- Capacity recommendations
|
||||
|
||||
3. **DISPLAY** projections:
|
||||
```
|
||||
🔮 PROJECTIONS
|
||||
══════════════════════════════════
|
||||
|
||||
At Current Velocity:
|
||||
- Next week: [X] stories (±[Y])
|
||||
- Next month: [X] stories (±[Y])
|
||||
|
||||
Capacity:
|
||||
- Current WIP: [X] stories
|
||||
- Optimal WIP limit: [X] stories
|
||||
- Capacity utilization: [X]%
|
||||
```
|
||||
|
||||
#### Phase 9: Recommendations
|
||||
1. **ANALYZE** metrics for improvement opportunities
|
||||
2. **GENERATE** specific, actionable recommendations:
|
||||
- Process optimizations
|
||||
- Bottleneck resolutions
|
||||
- Quality improvements
|
||||
- Tool suggestions
|
||||
|
||||
3. **PRIORITIZE** recommendations by impact
|
||||
|
||||
4. **DISPLAY** recommendations:
|
||||
```
|
||||
💡 RECOMMENDATIONS
|
||||
══════════════════════════════════
|
||||
|
||||
High Impact:
|
||||
1. [Specific improvement with metric basis]
|
||||
2. [Process optimization with expected gain]
|
||||
3. [Tool suggestion with benefit]
|
||||
|
||||
Quick Wins:
|
||||
- [Low-effort, high-value change]
|
||||
- [Simple process tweak]
|
||||
```
|
||||
|
||||
#### Phase 10: Metrics Dashboard
|
||||
1. **COMPILE** all metrics into summary dashboard
|
||||
2. **CALCULATE** trend indicators:
|
||||
- Velocity: trending up/down/stable
|
||||
- Quality: improving/declining/stable
|
||||
- Efficiency: percentage improvement
|
||||
|
||||
3. **EXTRACT** top insights from data
|
||||
4. **GENERATE** action items
|
||||
|
||||
5. **DISPLAY** complete dashboard:
|
||||
```
|
||||
📊 METRICS DASHBOARD
|
||||
══════════════════════════════════
|
||||
Period: [Date range]
|
||||
Generated: [Date and time]
|
||||
|
||||
HEADLINES:
|
||||
• Velocity: [↗ Trending up | ↘ Trending down | → Stable] ([X]%)
|
||||
• Quality: [Improving | Declining | Stable] ([X]%)
|
||||
• Efficiency: [X]% [improvement | decline] over last period
|
||||
|
||||
KEY INSIGHTS:
|
||||
• [Data-driven insight 1]
|
||||
• [Data-driven insight 2]
|
||||
• [Data-driven insight 3]
|
||||
|
||||
ACTION ITEMS:
|
||||
• [Prioritized action 1]
|
||||
• [Prioritized action 2]
|
||||
|
||||
NEXT REVIEW: [Suggested date]
|
||||
```
|
||||
|
||||
6. **OFFER** export option:
|
||||
```
|
||||
💾 Export metrics to /metrics/[date].md? (y/n)
|
||||
```
|
||||
|
||||
### OUTPUTS
|
||||
- Console display of all metric sections
|
||||
- Optional: `/metrics/[date].md` - Saved metrics report with timestamp
|
||||
|
||||
### RULES
|
||||
- MUST scan all story directories (backlog, development, review, qa, completed)
|
||||
- MUST calculate accurate time periods from story dates
|
||||
- MUST handle missing dates gracefully (exclude from time-based metrics)
|
||||
- SHOULD provide visual representations (bar charts) where helpful
|
||||
- SHOULD calculate trends over multiple periods
|
||||
- SHOULD generate actionable recommendations
|
||||
- NEVER modify story files (read-only operation)
|
||||
- ALWAYS display metric sources (which stories contributed)
|
||||
- ALWAYS include confidence levels for predictions
|
||||
- MUST handle empty directories (no stories found)
|
||||
|
||||
## Dashboard Layout
|
||||
|
||||
```
|
||||
📊 METRICS DASHBOARD
|
||||
══════════════════════════════════════════════════════════════════
|
||||
Period: [Start Date] to [End Date]
|
||||
Generated: [Timestamp]
|
||||
|
||||
📈 VELOCITY METRICS
|
||||
─────────────────────────────────────
|
||||
Current Period:
|
||||
- Stories completed: [count]
|
||||
- Average cycle time: [X] days
|
||||
- Throughput: [X] stories/week
|
||||
|
||||
Trend (Last 4 Weeks):
|
||||
Week 1: ████████ 8 stories
|
||||
Week 2: ██████ 6 stories
|
||||
Week 3: █████████ 9 stories
|
||||
Week 4: ███████ 7 stories
|
||||
|
||||
Status: ↗ Trending up (15%)
|
||||
|
||||
⏱️ CYCLE TIME ANALYSIS
|
||||
─────────────────────────────────────
|
||||
Average by Stage:
|
||||
- Development: [X] days
|
||||
- Review: [X] hours
|
||||
- QA: [X] hours
|
||||
- Total: [X] days
|
||||
|
||||
Outliers:
|
||||
- Fastest: [STORY-ID] - [X] days
|
||||
- Slowest: [STORY-ID] - [X] days
|
||||
|
||||
Bottlenecks:
|
||||
- [Stage]: [X]% above average
|
||||
|
||||
🎯 QUALITY METRICS
|
||||
─────────────────────────────────────
|
||||
Pass Rate:
|
||||
- First-time pass: [X]%
|
||||
- Average rework cycles: [X]
|
||||
|
||||
Bug Detection:
|
||||
- Avg bugs in review: [X]
|
||||
- Avg bugs in QA: [X]
|
||||
- Production incidents: [count]
|
||||
|
||||
Testing:
|
||||
- Avg test cases: [X]
|
||||
- Coverage target met: [X]%
|
||||
|
||||
Stability:
|
||||
- Rollback rate: [X]%
|
||||
|
||||
📊 STORY SIZE DISTRIBUTION
|
||||
─────────────────────────────────────
|
||||
Small (1-2 days): ████████ 40% ([count])
|
||||
Medium (3-5 days): ██████ 30% ([count])
|
||||
Large (5+ days): ██████ 30% ([count])
|
||||
|
||||
Recommendation: [Sizing guidance]
|
||||
|
||||
🔧 TECH STACK USAGE
|
||||
─────────────────────────────────────
|
||||
Most Used:
|
||||
- [Technology]: [X] stories
|
||||
- [Framework]: [X] stories
|
||||
|
||||
Recent Additions:
|
||||
- [New Tech]: Added [date]
|
||||
|
||||
📋 DEVELOPMENT PATTERNS
|
||||
─────────────────────────────────────
|
||||
Productivity:
|
||||
- Most productive day: [Day]
|
||||
- Peak completion time: [Time range]
|
||||
- Avg stories/week: [X]
|
||||
|
||||
Common Blockers:
|
||||
- [Blocker]: [X] occurrences
|
||||
|
||||
🔮 PROJECTIONS
|
||||
─────────────────────────────────────
|
||||
At Current Velocity:
|
||||
- Next week: [X] stories (±[Y])
|
||||
- Next month: [X] stories (±[Y])
|
||||
|
||||
Capacity:
|
||||
- Current WIP: [X] stories
|
||||
- Optimal WIP limit: [X]
|
||||
- Utilization: [X]%
|
||||
|
||||
💡 RECOMMENDATIONS
|
||||
─────────────────────────────────────
|
||||
High Impact:
|
||||
1. [Specific improvement]
|
||||
2. [Process optimization]
|
||||
3. [Tool suggestion]
|
||||
|
||||
Quick Wins:
|
||||
- [Low-effort improvement]
|
||||
|
||||
══════════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: All-Time Metrics
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-metrics
|
||||
|
||||
OUTPUT:
|
||||
→ Scanning story directories...
|
||||
→ Found 45 stories across all stages
|
||||
→ Analyzing velocity, cycle time, and quality...
|
||||
|
||||
📊 METRICS DASHBOARD
|
||||
══════════════════════════════════════════════════════════════════
|
||||
Period: All Time (Jan 1, 2025 - Oct 1, 2025)
|
||||
Generated: Oct 1, 2025 at 2:30 PM
|
||||
|
||||
📈 VELOCITY METRICS
|
||||
─────────────────────────────────────
|
||||
Current Period:
|
||||
- Stories completed: 42
|
||||
- Average cycle time: 4.2 days
|
||||
- Throughput: 6.8 stories/week
|
||||
|
||||
Trend (Last 4 Weeks):
|
||||
Week 1: ████████ 8 stories
|
||||
Week 2: ██████ 6 stories
|
||||
Week 3: █████████ 9 stories
|
||||
Week 4: ███████ 7 stories
|
||||
|
||||
Status: ↗ Trending up (12%)
|
||||
|
||||
[Additional sections...]
|
||||
|
||||
💾 Export metrics to /metrics/2025-10-01.md? (y/n)
|
||||
```
|
||||
|
||||
### Example 2: Monthly Metrics
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-metrics month
|
||||
|
||||
OUTPUT:
|
||||
→ Scanning story directories...
|
||||
→ Found 28 stories in last 30 days
|
||||
→ Analyzing September 2025 data...
|
||||
|
||||
📊 METRICS DASHBOARD
|
||||
══════════════════════════════════════════════════════════════════
|
||||
Period: Sep 1, 2025 - Sep 30, 2025
|
||||
Generated: Oct 1, 2025 at 2:30 PM
|
||||
|
||||
📈 VELOCITY METRICS
|
||||
─────────────────────────────────────
|
||||
Current Period:
|
||||
- Stories completed: 28
|
||||
- Average cycle time: 3.8 days
|
||||
- Throughput: 7.0 stories/week
|
||||
|
||||
Status: ↗ Trending up (18% vs August)
|
||||
|
||||
[Additional sections...]
|
||||
```
|
||||
|
||||
### Example 3: No Stories Found
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-metrics week
|
||||
|
||||
OUTPUT:
|
||||
→ Scanning story directories...
|
||||
→ No stories found in last 7 days
|
||||
|
||||
⚠️ INSUFFICIENT DATA
|
||||
══════════════════════════════════════
|
||||
No completed stories found in the specified period.
|
||||
|
||||
Suggestions:
|
||||
- Try a longer period: /sdd:story-metrics month
|
||||
- Check if stories are marked as completed
|
||||
- Verify story dates are set correctly
|
||||
|
||||
Current WIP:
|
||||
- Development: 2 stories
|
||||
- Review: 1 story
|
||||
- QA: 1 story
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### No Completed Stories
|
||||
- DETECT empty completed directory
|
||||
- DISPLAY insufficient data message
|
||||
- SHOW current WIP as context
|
||||
- SUGGEST longer time period
|
||||
|
||||
### Missing Dates in Stories
|
||||
- SKIP stories without started/completed dates
|
||||
- LOG warning about incomplete data
|
||||
- CALCULATE metrics from available data
|
||||
- NOTE data quality issue in dashboard
|
||||
|
||||
### Single Story in Period
|
||||
- CALCULATE limited metrics
|
||||
- WARN about small sample size
|
||||
- AVOID trend calculations
|
||||
- PROVIDE useful context instead
|
||||
|
||||
### Inconsistent Story Format
|
||||
- PARSE flexibly with fallbacks
|
||||
- LOG parsing warnings
|
||||
- EXTRACT what's available
|
||||
- CONTINUE with best-effort analysis
|
||||
|
||||
## Error Handling
|
||||
- **No story directories**: Report missing directories, suggest `/sdd:project-init`
|
||||
- **Permission errors**: Report specific access issues
|
||||
- **Malformed story files**: Skip problematic files, log warnings
|
||||
- **Invalid period parameter**: Show valid options, use default
|
||||
- **Zero stories**: Provide helpful guidance instead of empty metrics
|
||||
|
||||
## Performance Considerations
|
||||
- Efficient file scanning (single pass per directory)
|
||||
- Lazy date parsing (only for period-filtered stories)
|
||||
- Cached calculations within single run
|
||||
- Streaming output for large datasets
|
||||
- Typical completion time: < 2 seconds for 100 stories
|
||||
|
||||
## Related Commands
|
||||
- `/sdd:story-patterns` - Identify recurring patterns in stories
|
||||
- `/sdd:story-tech-debt` - Analyze technical debt from stories
|
||||
- `/sdd:project-status` - View current story statuses
|
||||
- `/sdd:story-list` - List stories with filters
|
||||
|
||||
## Constraints
|
||||
- ✅ MUST be read-only (no file modifications)
|
||||
- ✅ MUST handle missing/malformed data gracefully
|
||||
- ✅ MUST provide accurate calculations
|
||||
- ⚠️ SHOULD visualize trends with charts
|
||||
- 📊 SHOULD include confidence intervals for predictions
|
||||
- 💡 SHOULD generate actionable recommendations
|
||||
- 🔍 MUST show data sources for transparency
|
||||
- ⏱️ MUST complete analysis in reasonable time (< 5s)
|
||||
Reference in New Issue
Block a user