Multi-Period Comparison Feature
Overview
Added capability to compare team metrics across multiple time periods, providing a clear view of performance trends over time. The default behavior remains unchanged (single period with previous period comparison), but users can now request comparisons across 2, 3, 4, or more periods.
Usage
Default Behavior (Unchanged)
python kpi_cli.py team UAS
Shows current period metrics with trend indicators comparing to the previous period. Includes detailed metrics with outliers.
Multi-Period Comparison
python kpi_cli.py team UAS --periods 3
Shows a table-formatted comparison across 3 consecutive periods (current, previous, -2 periods).
python kpi_cli.py team O2C --periods 4
Shows comparison across 4 periods.
Features
1. Period Definitions
Each report clearly shows the date ranges for each period:
Period Definitions:
Current 2025-10-22 to 2025-11-21
Previous 2025-09-22 to 2025-10-22
-2 periods 2025-08-23 to 2025-09-22
2. Tabular Comparison
Metrics are displayed in tables with columns for each period, making it easy to see trends:
š VELOCITY (items completed)
----------------------------------------------------------------------------------------------------
Period Current Previous -2 periods
----------------------------------------------------------------------------------------------------
Velocity 65 50 146
Change ā ā +30.0% ā -65.8%
3. Trend Indicators
- ā = Increase (good for velocity, bad for time metrics)
- ā = Decrease (bad for velocity, good for time metrics)
- ā = No significant change (< 5% change)
- ā = Not applicable (no previous period to compare)
Trend interpretation is context-aware: - Velocity: Higher is better ā ā for increase - Lead Time/Cycle Time: Lower is better ā ā for decrease - Change Failure Rate: Lower is better ā ā for decrease
4. Metrics Included
The multi-period comparison includes:
- Velocity: Items completed per period
- Work in Progress (WIP): Current WIP load (point-in-time)
- Lead Time: Median, 85th percentile, and average
- With period-over-period change percentages
- Cycle Time: Median, 85th percentile, and average
- With period-over-period change percentages
- Work Distribution: Current period breakdown (Feature/Defect/Risk/Debt)
- Change Failure Rate: Percentage with trends
5. Automatic Period Calculation
Periods are calculated automatically going backwards in time: - Period 0 (Current): Last N days from now - Period 1 (Previous): N days before current period - Period 2 (-2 periods): N days before previous period - And so on...
Where N is the configured period length (default: 30 days).
Implementation Details
New Methods
KpiService.calculate_team_metrics_multi_period()
def calculate_team_metrics_multi_period(
team_id: str,
num_periods: int = 2,
period_days: Optional[int] = None
) -> List[Dict[str, Any]]
Calculates metrics for multiple consecutive periods. Returns a list of period dictionaries ordered from most recent to oldest.
CLI Updates
Updated command syntax:
python kpi_cli.py team <TEAM_ID> [--periods N]
N=1or omitted: Default behavior (detailed view with trends)Nā„2: Multi-period table comparison
New display function:
def print_multi_period_comparison(periods_data: list)
Renders metrics in table format with trend indicators and period-over-period comparisons.
Example Outputs
2-Period Comparison (Current vs Previous)
python kpi_cli.py team LGMT --periods 2
Shows a compact comparison between current and previous period. Useful for quick trend checking.
3-Period Comparison
python kpi_cli.py team O2C --periods 3
Shows current, previous, and -2 periods. Good for identifying medium-term trends.
4+ Period Comparison
python kpi_cli.py team UAS --periods 4
Shows longer-term trends. Useful for quarterly reviews or understanding seasonal patterns.
Key Design Decisions
1. Backward Compatibility
The default behavior (single period with trends) is unchanged. Users must explicitly request multi-period comparison with --periods N.
2. Table Format
Multi-period data is displayed in tables rather than verbose text format to: - Make trends immediately visible - Reduce visual clutter - Enable easy column-wise comparison - Support comparison of many periods without overwhelming output
3. Trend Direction
Arrows are context-aware: - For velocity (higher is better): ā means improvement - For time metrics (lower is better): ā means improvement - This makes trends immediately interpretable without mental calculation
4. Work Distribution
Only shown for current period in multi-period view to save space. Historical distributions can be viewed using single-period mode.
5. No Outlier Details
Multi-period view focuses on aggregate trends. For detailed outlier analysis, use single-period mode:
python kpi_cli.py team UAS # Shows outliers
Use Cases
1. Monthly Reviews
python kpi_cli.py team UAS --periods 3
Compare last 3 months to identify trends and prepare for retrospectives.
2. Quarterly Planning
python kpi_cli.py team O2C --periods 4
Review last quarter's performance to inform next quarter's goals.
3. Process Changes
python kpi_cli.py team SSH --periods 6
After implementing process changes, track metrics over 6 periods to measure impact.
4. Quick Trend Check
python kpi_cli.py team ACQREG --periods 2
Fast comparison of current vs previous period for daily/weekly check-ins.
Benefits
- Trend Visibility: See performance trends at a glance
- Pattern Recognition: Identify seasonal patterns or anomalies
- Impact Measurement: Measure impact of process changes over time
- Data-Driven Decisions: Make informed decisions based on historical trends
- Flexible Analysis: Choose the right time window for your analysis needs
Technical Notes
Performance
Each period calculation is independent, using the same underlying metrics calculator. For N periods: - Time complexity: O(N Ć M) where M is the number of issues - Memory: Minimal (only aggregate metrics stored, not raw issues)
Error Handling
If a period cannot be calculated (e.g., insufficient data), it's skipped with a warning. Other periods are still displayed.
Date Boundaries
Periods are non-overlapping and consecutive: - Current: [now - N days, now] - Previous: [now - 2N days, now - N days] - -2 periods: [now - 3N days, now - 2N days]
This ensures clean separation between periods with no overlap.
Future Enhancements
Potential future improvements:
1. Custom period length per comparison: --periods 3 --days 14 for 3 periods of 14 days each
2. Export to CSV/JSON: Save multi-period data for external analysis
3. Visual charts: ASCII charts showing trends over time
4. Organization-wide multi-period: Compare all teams across multiple periods
5. Period-over-period benchmarks: Show industry benchmarks for each metric
Implementation Date: 2025-11-21 Author: Claude Code Status: ā Implemented and Tested