Headroom - Foundation

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

@@ -0,0 +1,73 @@
+## ADDED Requirements
+
+### Requirement: Generate variance report
+The system SHALL generate reports comparing planned allocations vs actual logged hours.
+
+#### Scenario: View monthly variance report
+- **WHEN** viewing variance report for February 2026
+- **THEN** the system displays all projects with:
+  - Allocated hours (planned)
+  - Actual hours (logged)
+  - Variance (actual - planned)
+  - Variance percentage ((variance / planned) × 100%)
+
+#### Scenario: Positive variance (over-delivery)
+- **WHEN** a project had 40 hours allocated
+- **AND** team member logged 45 hours actual
+- **THEN** the system displays variance of +5 hours (+12.5%)
+- **AND** flags as "Over-delivery"
+
+#### Scenario: Negative variance (under-delivery)
+- **WHEN** a project had 40 hours allocated
+- **AND** team member logged 32 hours actual
+- **THEN** the system displays variance of -8 hours (-20%)
+- **AND** flags as "Under-delivery"
+
+### Requirement: Variance by project
+The system SHALL show variance aggregated by project.
+
+#### Scenario: Project variance summary
+- **WHEN** viewing variance for "Project X" with 120 hours allocated across 3 team members
+- **AND** actual hours logged total 110 hours
+- **THEN** the system displays project-level variance of -10 hours (-8.3%)
+
+### Requirement: Variance by team member
+The system SHALL show variance aggregated by team member.
+
+#### Scenario: Person variance summary
+- **WHEN** "John Doe" had 140 hours total allocated across multiple projects
+- **AND** logged 135 hours actual
+- **THEN** the system displays person-level variance of -5 hours (-3.6%)
+
+#### Scenario: Consistent over-delivery
+- **WHEN** a team member has positive variance for 3 consecutive months
+- **THEN** the system flags the pattern "Consistently working more than allocated"
+
+### Requirement: Filter variance report
+The system SHALL allow filtering variance reports by date range, project, team, or person.
+
+#### Scenario: Filter by date range
+- **WHEN** filtering variance report for Q1 2026
+- **THEN** the system displays variance for January, February, and March
+- **AND** calculates total variance across the quarter
+
+### Requirement: Variance trend analysis
+The system SHALL show variance trends over time.
+
+#### Scenario: Variance trend chart
+- **WHEN** viewing variance trends for a team member over 6 months
+- **THEN** the system displays a chart showing variance percentage for each month
+- **AND** highlights months with significant variance (> ±15%)
+
+### Requirement: Root cause indicators
+The system SHALL highlight patterns that may explain variance.
+
+#### Scenario: Under-delivery correlation with PTO
+- **WHEN** a team member has negative variance in a month
+- **AND** the team member had PTO during that month
+- **THEN** the system notes "PTO may have contributed to under-delivery"
+
+#### Scenario: Over-delivery correlation with over-allocation
+- **WHEN** a team member has positive variance
+- **AND** the team member was over-allocated (> 100% capacity)
+- **THEN** the system notes "Team member worked extra hours beyond allocation"