Headroom - Foundation

openspec/changes/headroom-foundation/specs/utilization-reporting/spec.md

@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: Generate utilization summary report
+The system SHALL generate reports showing team and individual utilization trends over time.
+
+#### Scenario: View team utilization report
+- **WHEN** a manager requests utilization report for February-April 2026
+- **THEN** the system displays team-level utilization for each month
+- **AND** shows individual team member utilization for each month
+- **AND** calculates average utilization across the period
+
+#### Scenario: Utilization trend visualization
+- **WHEN** viewing utilization report
+- **THEN** the system displays a chart showing utilization percentage trend over time
+- **AND** highlights months with low utilization (< 70%) in blue
+- **AND** highlights months with optimal utilization (80-100%) in green
+- **AND** highlights months with over-utilization (> 100%) in red
+
+### Requirement: Filter utilization by team member
+The system SHALL allow filtering utilization reports by individual team member or role.
+
+#### Scenario: View individual utilization
+- **WHEN** filtering to show utilization for "John Doe"
+- **THEN** the system displays John's monthly utilization percentages
+- **AND** shows running (YTD) utilization
+- **AND** shows overall (monthly) utilization for each month
+
+#### Scenario: View role-based utilization
+- **WHEN** filtering to show utilization for "Backend Developer" role
+- **THEN** the system displays average utilization for all Backend Developers
+- **AND** shows individual breakdown for each team member in that role
+
+### Requirement: Compare planned vs actual utilization
+The system SHALL show variance between planned utilization (allocations) and actual utilization (logged hours).
+
+#### Scenario: Utilization variance report
+- **WHEN** a team member had 87.5% planned utilization in February
+- **AND** logged hours resulting in 81.25% actual utilization
+- **THEN** the system displays variance of -6.25 percentage points
+- **AND** flags under-delivery
+
+#### Scenario: Over-delivery variance
+- **WHEN** a team member had 87.5% planned utilization
+- **AND** logged hours resulting in 95% actual utilization
+- **THEN** the system displays variance of +7.5 percentage points
+- **AND** flags over-delivery (worked more than allocated)
+
+### Requirement: Utilization distribution chart
+The system SHALL display utilization distribution showing how many team members fall into each utilization band.
+
+#### Scenario: View utilization distribution
+- **WHEN** viewing team utilization report for February
+- **THEN** the system shows how many team members are in each band:
+  - Under-utilized (< 70%): 2 team members
+  - Optimal (70-100%): 8 team members
+  - Over-utilized (> 100%): 3 team members
+
+### Requirement: Filter by date range
+The system SHALL allow selecting custom date ranges for utilization reports.
+
+#### Scenario: Quarter-over-quarter comparison
+- **WHEN** selecting Q1 2026 (Jan-Mar) and Q2 2026 (Apr-Jun)
+- **THEN** the system displays utilization comparison between the two quarters
+
+### Requirement: Identify underutilized capacity
+The system SHALL highlight team members with consistently low utilization.
+
+#### Scenario: Flag underutilized team members
+- **WHEN** a team member has utilization below 70% for 3 consecutive months
+- **THEN** the system flags the team member in the report with warning "Underutilized capacity"
+- **AND** calculates total wasted capacity in hours