# capacity-planning Specification

## Purpose
TBD - created by archiving change headroom-foundation. Update Purpose after archive.
## Requirements
### Requirement: Calculate individual capacity
The system SHALL calculate individual team member capacity for a given month based on availability, holidays, PTO, and weekends.

#### Scenario: Calculate capacity for full month
- **WHEN** calculating capacity for a team member with full availability (1.0) for all working days in February 2026
- **AND** February has 20 working days (28 days - 8 weekend days)
- **AND** the team member has no PTO or holidays
- **THEN** the system calculates individual capacity as 20 person-days

#### Scenario: Calculate capacity with half-day availability
- **WHEN** a team member has availability of 0.5 for 10 working days in a month
- **THEN** the system calculates capacity as 5 person-days (10 days × 0.5)

#### Scenario: Calculate capacity with PTO
- **WHEN** a team member has PTO for 3 working days in a month
- **AND** the month has 22 working days
- **AND** the team member has full availability (1.0) for all other days
- **THEN** the system calculates capacity as 19 person-days (22 - 3 days PTO)

#### Scenario: Calculate capacity with holidays
- **WHEN** a month has 2 company holidays
- **AND** a team member has 22 working days after removing weekends
- **AND** the team member has full availability (1.0)
- **THEN** the system calculates capacity as 20 person-days (22 - 2 holidays)

#### Scenario: Calculate capacity with mixed availability
- **WHEN** a team member has 10 days at 1.0 availability, 5 days at 0.5 availability, and 3 days at 0 availability in a month
- **THEN** the system calculates capacity as 12.5 person-days (10×1.0 + 5×0.5 + 3×0)

### Requirement: Calculate team capacity
The system SHALL calculate total team capacity by summing individual capacities for all active team members.

#### Scenario: Calculate team capacity for month
- **WHEN** Team Member A has 20 person-days capacity
- **AND** Team Member B has 18 person-days capacity
- **AND** Team Member C has 15 person-days capacity
- **THEN** the system calculates team capacity as 53 person-days

#### Scenario: Exclude inactive team members from team capacity
- **WHEN** calculating team capacity
- **AND** one team member has active status set to false
- **THEN** the system excludes the inactive team member from the team capacity calculation

### Requirement: Calculate possible revenue
The system SHALL calculate possible revenue based on team capacity and hourly rates.

#### Scenario: Calculate possible revenue for team
- **WHEN** Team Member A has 160 hours capacity at $150/hour
- **AND** Team Member B has 144 hours capacity at $125/hour
- **AND** Team Member C has 120 hours capacity at $175/hour
- **THEN** the system calculates possible revenue as $63,000 (160×$150 + 144×$125 + 120×$175)

### Requirement: Track availability per day
The system SHALL allow setting daily availability as 0 (unavailable), 0.5 (half day), or 1.0 (full day).

#### Scenario: Set full day availability
- **WHEN** setting availability for a specific date to 1.0
- **THEN** the system records the team member as fully available for that day

#### Scenario: Set half day availability
- **WHEN** setting availability for a specific date to 0.5
- **THEN** the system records the team member as half-day available for that day

#### Scenario: Set unavailable
- **WHEN** setting availability for a specific date to 0
- **THEN** the system records the team member as unavailable for that day

#### Scenario: Reject invalid availability values
- **WHEN** attempting to set availability to a value other than 0, 0.5, or 1.0
- **THEN** the system rejects the input with validation error "Availability must be 0, 0.5, or 1.0"

### Requirement: Manage holidays
The system SHALL allow defining company-wide holidays that reduce available working days for all team members.

#### Scenario: Add company holiday
- **WHEN** an admin defines December 25, 2026 as a company holiday "Christmas Day"
- **THEN** the system marks that date as a non-working day for all team members

#### Scenario: Holidays affect capacity calculation
- **WHEN** calculating capacity for a month with 2 company holidays
- **THEN** the system automatically excludes those days from all team members' capacity calculations

### Requirement: Manage PTO requests
The system SHALL allow team members to request PTO which reduces their individual capacity.

#### Scenario: Submit PTO request
- **WHEN** a team member submits PTO for February 10-12, 2026
- **THEN** the system creates a PTO record with start date, end date, and status "approved"

#### Scenario: Approve PTO request
- **WHEN** a manager approves a PTO request
- **THEN** the system updates the PTO status to "approved"
- **AND** the system automatically reduces the team member's capacity for those dates to 0

#### Scenario: Delete PTO request
- **WHEN** a manager deletes an existing PTO request
- **THEN** the PTO record is removed
- **AND** individual, team, and revenue capacity caches for affected months are refreshed

#### Scenario: PTO affects capacity calculation
- **WHEN** calculating capacity for a team member with approved PTO for 3 days
- **THEN** the system excludes those 3 days from the capacity calculation

#### Scenario: Override PTO day availability
- **WHEN** a PTO day is manually set to half day availability (0.5)
- **THEN** the system keeps the PTO marker for that date
- **AND** the capacity calculation uses the explicit availability override instead of forcing 0

