Headroom - Foundation

openspec/changes/headroom-foundation/specs/allocation-validation/spec.md

@@ -0,0 +1,87 @@
+## ADDED Requirements
+
+### Requirement: Detect over-allocation
+The system SHALL flag allocations that exceed approved estimates with RED indicator.
+
+#### Scenario: Project over-allocated
+- **WHEN** a project has approved estimate of 100 hours
+- **AND** total allocations sum to 120 hours
+- **THEN** the system displays RED indicator with text "120% allocated (OVER by 20 hours)"
+
+#### Scenario: Over-allocation threshold
+- **WHEN** total allocations exceed approved estimate by more than 5%
+- **THEN** the system displays RED flag
+- **AND** the system shows warning message "Will overcharge client"
+
+### Requirement: Detect under-allocation
+The system SHALL flag allocations that fall short of approved estimates with YELLOW indicator.
+
+#### Scenario: Project under-allocated
+- **WHEN** a project has approved estimate of 100 hours
+- **AND** total allocations sum to 80 hours
+- **THEN** the system displays YELLOW indicator with text "80% allocated (UNDER by 20 hours)"
+
+#### Scenario: Under-allocation warning
+- **WHEN** total allocations are less than approved estimate by more than 5%
+- **THEN** the system displays YELLOW flag
+- **AND** the system shows warning message "Will undercharge client (revenue loss)"
+
+### Requirement: Display optimal allocation
+The system SHALL display GREEN indicator when allocations match approved estimates.
+
+#### Scenario: Perfect allocation
+- **WHEN** a project has approved estimate of 100 hours
+- **AND** total allocations sum to exactly 100 hours
+- **THEN** the system displays GREEN indicator with text "100% allocated (OPTIMAL)"
+
+#### Scenario: Within tolerance
+- **WHEN** a project has approved estimate of 100 hours
+- **AND** total allocations sum to 102 hours (within 5% tolerance)
+- **THEN** the system displays GREEN indicator with text "102% allocated (within tolerance)"
+
+### Requirement: Validate person capacity
+The system SHALL warn when a team member's allocations exceed their monthly capacity.
+
+#### Scenario: Person under capacity
+- **WHEN** a team member has capacity of 160 hours
+- **AND** total allocations sum to 120 hours
+- **THEN** the system displays utilization as 75% with no warning
+
+#### Scenario: Person at capacity
+- **WHEN** a team member has capacity of 160 hours
+- **AND** total allocations sum to 160 hours
+- **THEN** the system displays utilization as 100% with GREEN indicator
+
+#### Scenario: Person over capacity
+- **WHEN** a team member has capacity of 160 hours
+- **AND** total allocations sum to 180 hours
+- **THEN** the system displays utilization as 113% with YELLOW warning "Over-allocated by 20 hours"
+
+#### Scenario: Person severely over capacity
+- **WHEN** a team member has capacity of 160 hours
+- **AND** total allocations sum to 200 hours (125% or more)
+- **THEN** the system displays utilization as 125% with RED warning "Severely over-allocated by 40 hours"
+
+### Requirement: Aggregate validation across months
+The system SHALL validate allocations across multiple months for multi-month projects.
+
+#### Scenario: Multi-month project validation
+- **WHEN** a project has approved estimate of 120 hours
+- **AND** forecasted effort is: Feb 40h, Mar 60h, Apr 20h
+- **AND** actual allocations are: Feb 38h, Mar 62h, Apr 20h
+- **THEN** the system validates total allocations (38+62+20=120) against approved estimate (120)
+- **AND** displays overall GREEN indicator
+- **AND** displays monthly warnings where allocations deviate from forecast
+
+### Requirement: Real-time validation feedback
+The system SHALL provide immediate validation feedback as allocations are created or modified.
+
+#### Scenario: Immediate feedback on create
+- **WHEN** a manager creates an allocation that causes a project to exceed approved estimate
+- **THEN** the system immediately displays RED indicator on the allocation matrix
+- **AND** the system shows tooltip "This allocation causes project over-allocation"
+
+#### Scenario: Immediate feedback on update
+- **WHEN** a manager increases an allocation and the team member becomes over-capacity
+- **THEN** the system immediately updates the utilization percentage
+- **AND** the system changes the team member's column header color to YELLOW or RED