# Specification: 007-employee-shift-requests

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-31 |
| **Current Phase** | PLAN Complete - Ready for Implementation |
| **Last Updated** | 2025-12-31 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Full PRD with push notification integration |
| solution-design.md | completed | All 5 ADRs approved, full technical design |
| implementation-plan.md | completed | 6 phases, 220+ tasks with TDD structure, Codex-reviewed |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-31 | Started with PRD | User chose comprehensive documentation path |
| 2025-12-31 | Push notifications required | User explicitly requested notification integration |
| 2025-12-31 | PRD Codex Review completed | Added state machine, eligibility rules, privacy policy per review |
| 2025-12-31 | SDD completed | Full technical design with Clean Architecture, Riverpod 3.x |
| 2025-12-31 | ADR-1: Single Provider | Use one ShiftRequestsProvider for both time-off and swap requests |
| 2025-12-31 | ADR-2: Separate TeamScheduleProvider | Team schedule browsing in its own provider |
| 2025-12-31 | ADR-3: Optimistic Updates | Show submitted requests immediately, revert on error |
| 2025-12-31 | ADR-4: Backend Eligibility | Backend calculates swap eligibility per shift |
| 2025-12-31 | ADR-5: Sealed Classes | Use sealed class state machines (follows existing patterns) |
| 2025-12-31 | PLAN completed | 6 phases covering domain→data→presentation→UI→integration→validation |
| 2025-12-31 | PLAN Codex Review completed | Added risks, DoD, analytics, swap expiration, offline UI, notification matrix |

## Codex PLAN Review Summary (2025-12-31)

**Review Tool:** OpenAI Codex (gpt-5.2)

**Blockers Resolved (3):**
1. ✅ B1: Added analytics/tracking events tasks (T5.10.*) covering all PRD events
2. ✅ B2: Made T3.7.1 explicit - submission states included in main provider per ADR-1
3. ✅ B3: Added swap expiration/invalidated state handling (T1.4.5-6, T4.7.7-8, T4.7.13)

**Important Issues Resolved (8):**
1. ✅ I1: Fixed phase dependency diagram - Phase 4 now correctly requires Phase 3
2. ✅ I2: Made T5.8.1 explicit with clear inspection → decision → implementation flow
3. ✅ I3: Added notification ordering tests (T5.9.4)
4. ✅ I4: Added NotificationSettingsScreen request toggle tests (T5.8.3)
5. ✅ I5: Added notification type matrix tests (T5.9.1-4) for all 9 types
6. ✅ I6: Added Implementation Risks & Mitigations section with 6 risks mapped to tasks
7. ✅ I7: Added per-phase Definition of Done checklists (after each Validate section)
8. ✅ I8: Added offline queue UI behavior tasks (T5.11.*) with queued state display

**Enhancements Applied (4):**
1. ✅ E1: Added parallel work merge points notation in Phase Dependencies
2. ✅ E2: Added early integration checkpoint after Phase 3 (T3.9.*)
3. ✅ E3: Added within-phase dependency note for Phase 4 parallel widgets
4. ✅ E4: Added Phase 5 smoke checklist (T5.12.*) for manual verification

**PLAN Status:** Ready for Implementation ✅

---

## Codex PRD Review Summary (2025-12-31)

**Review Tool:** OpenAI Codex (gpt-5.2)

**Blockers Resolved:**
1. ✅ Added Request State Machine with transitions and notification mappings
2. ✅ Added Swap Eligibility Rules (who can see, which shifts eligible, hard blocks vs warnings)
3. ✅ Added Team Schedule Visibility & Privacy policy

**Important Improvements Made:**
- Added 2 new user stories: Approval Status Visibility, Offline/Push Disabled Fallback
- Added Error States and Messages table
- Added network loss and timezone edge cases
- Added Guardrail Metrics (opt-out rate, crash-free, abandonment)
- Added baseline measurement approach for KPIs

**Deferred to SDD:**
- Backend API contract details
- Idempotency key implementation
- Analytics pipeline configuration

## Codex SDD Review Summary (2025-12-31)

**Review Tool:** OpenAI Codex (o3)

**Blockers Resolved (3):**
1. ✅ B1: Added Notification Preferences Integration section referencing existing NotificationSettingsScreen
2. ✅ B2: Added Data Refresh Strategy (pull-to-refresh, auto-refresh on focus, staleness check) for push fallback
3. ✅ B3: Fixed provider boundary inconsistency in sequence diagrams (TeamScheduleProvider vs ShiftRequestsProvider)

**Important Issues Resolved (7):**
1. ✅ I1: Added full API Contract Specifications with JSON request/response schemas and error codes
2. ✅ I2: Added PRD → Design Traceability section with business rule ownership table (client vs backend)
3. ✅ I3: Added Team Schedule Privacy Specification table (allowed/disallowed fields)
4. ✅ I4: Added SwapRequestFilter class for filtering swap requests by status/date/initiator
5. ✅ I5: Added Offline Queue Component design (OfflineQueueService with interface specification)
6. ✅ I6: Added Notification Payload Schema with JSON structure
7. ✅ I7: Added Timezone Handling section with principles, DST edge cases, and parsing strategy

**Enhancements Noted (Deferred to Implementation):**
- E1: Analytics event implementation details
- E2: Complete test matrix with all scenarios
- E3: Pagination for large request histories
- E4: Rate limiting considerations
- E5: Submission state clarification in edge cases

**SDD Status:** Ready for Implementation Plan ✅

## Context

**Feature Request:** Add employee day off requests, swap shift requests, view full schedule (so you can select a shift to swap). Finish out all of the employee side endpoints except chat.

**Key Capabilities:**
- **Day Off Requests**: Submit time-off/day-off requests with date range and reason
- **Shift Swap Requests**: Request to swap shifts with coworkers
- **Full Schedule View**: View team schedule to select shifts for swapping
- **Request Status Tracking**: View pending, approved, denied request history

**Related Specs:**
- 003-open-shifts (shift claiming, already implemented)
- 004-schedule-viewing (weekly schedule, already implemented)
- Backend: 013-employee-scheduling

**Existing Infrastructure:**
- Schedule entities and viewing (ScheduledShift, WeeklySchedule)
- Open shift claiming (OpenShift, ClaimResult)
- Push notifications for approvals/denials
- Store context and auth

---
*This file is managed by the specification-management skill.*