Headroom - Foundation

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

@@ -0,0 +1,91 @@
+## ADDED Requirements
+
+### Requirement: Calculate running utilization
+The system SHALL calculate running utilization as (Allocated hours YTD) / (Capacity YTD) × 100%.
+
+#### Scenario: Calculate YTD utilization in March
+- **WHEN** a team member has capacity: Jan 160h, Feb 160h, Mar 160h (YTD total: 480h)
+- **AND** the team member has allocations: Jan 140h, Feb 150h, Mar 160h (YTD total: 450h)
+- **THEN** the system calculates running utilization as 93.75% (450 / 480 × 100%)
+
+#### Scenario: Running utilization at start of year
+- **WHEN** calculating running utilization in January
+- **AND** the team member has capacity of 160h and allocations of 120h
+- **THEN** the system calculates running utilization as 75% (120 / 160 × 100%)
+
+### Requirement: Calculate overall utilization
+The system SHALL calculate overall utilization as (Allocated hours this month) / (Capacity this month) × 100%.
+
+#### Scenario: Calculate monthly utilization
+- **WHEN** a team member has capacity of 160 hours for February
+- **AND** the team member has total allocations of 140 hours for February
+- **THEN** the system calculates overall utilization as 87.5% (140 / 160 × 100%)
+
+#### Scenario: Full utilization
+- **WHEN** a team member has capacity of 160 hours
+- **AND** allocations of exactly 160 hours
+- **THEN** the system calculates overall utilization as 100%
+
+#### Scenario: Over-utilization
+- **WHEN** a team member has capacity of 160 hours
+- **AND** allocations of 180 hours
+- **THEN** the system calculates overall utilization as 112.5% (180 / 160 × 100%)
+
+### Requirement: Display utilization alongside capacity
+The system SHALL display utilization percentages alongside capacity information in the allocation view.
+
+#### Scenario: Display capacity with utilization
+- **WHEN** viewing the allocation matrix for a team member
+- **THEN** the system displays capacity (e.g., "160h")
+- **AND** displays overall utilization percentage (e.g., "87.5%")
+- **AND** displays running utilization percentage (e.g., "YTD: 93.75%")
+
+### Requirement: Color-code utilization levels
+The system SHALL use color coding to indicate utilization levels.
+
+#### Scenario: Low utilization
+- **WHEN** overall utilization is below 70%
+- **THEN** the system displays the utilization in BLUE or GRAY (underutilized)
+
+#### Scenario: Optimal utilization
+- **WHEN** overall utilization is between 80% and 100%
+- **THEN** the system displays the utilization in GREEN (optimal)
+
+#### Scenario: High utilization
+- **WHEN** overall utilization is between 100% and 110%
+- **THEN** the system displays the utilization in YELLOW (caution)
+
+#### Scenario: Over-utilization
+- **WHEN** overall utilization exceeds 110%
+- **THEN** the system displays the utilization in RED (over-allocated)
+
+### Requirement: Calculate team-level utilization
+The system SHALL calculate average utilization across all team members.
+
+#### Scenario: Calculate team average utilization
+- **WHEN** Team Member A has 87.5% utilization
+- **AND** Team Member B has 93.75% utilization
+- **AND** Team Member C has 75% utilization
+- **THEN** the system calculates team average utilization as 85.4% ((87.5 + 93.75 + 75) / 3)
+
+#### Scenario: Exclude inactive team members from team utilization
+- **WHEN** calculating team-level utilization
+- **AND** one team member is inactive
+- **THEN** the system excludes the inactive team member from the average
+
+### Requirement: Track utilization trends over time
+The system SHALL provide historical utilization data for trend analysis.
+
+#### Scenario: View utilization trend for 6 months
+- **WHEN** viewing a team member's utilization history from January to June
+- **THEN** the system displays monthly utilization percentages for each month
+- **AND** the system shows a trend line or chart indicating increasing/decreasing utilization
+
+### Requirement: Compare allocated vs actual utilization
+The system SHALL calculate actual utilization based on logged hours for comparison with planned utilization.
+
+#### Scenario: Calculate actual utilization
+- **WHEN** a team member had 140 hours allocated (planned utilization: 87.5%)
+- **AND** the team member logged 130 hours actual (actual utilization: 81.25%)
+- **THEN** the system displays both planned and actual utilization side by side
+- **AND** the system shows variance of -6.25 percentage points