# /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)