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

4.1 KiB

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