# Specification: 027-wait-time-quick-wins

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-01-08 |
| **Current Phase** | Implementation Plan Complete - Ready for Implementation |
| **Last Updated** | 2026-01-08 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | All sections validated, Codex reviewed |
| solution-design.md | completed | All ADRs confirmed, Codex SDD reviewed 2026-01-08 |
| implementation-plan.md | completed | 6 phases, 174 tasks, 10 parallel groups (Codex reviewed) |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-01-08 | PLAN reviewed by Codex | Quality check for completeness and sequencing |
| 2026-01-08 | Added interface contracts to Phase 1 | Enables Phase 2 calculator TDD via mocks |
| 2026-01-08 | Added waitTimeFactorCache table operations | SDD component was not covered by tasks |
| 2026-01-08 | Added data quality logging tasks | SDD contract includes logging but tasks were missing |
| 2026-01-08 | Added timezone handling tests | Risk mitigation for dayOfWeek conversion |
| 2026-01-08 | Added mobile API integration test | SDD references endpoint but not tested |
| 2026-01-08 | PLAN created | 6 phases following TDD pattern, 174 tasks total |
| 2026-01-08 | PRD reviewed by Codex | Quality check before SDD |
| 2026-01-08 | Added Definitions section | Codex blocker: "Actual wait time" and "queue depth" undefined |
| 2026-01-08 | Reconciled data thresholds to 50 transactions/30 days | Codex blocker: conflicting thresholds (4 weeks vs 50 transactions) |
| 2026-01-08 | Added Factor Combination Rules | Codex blocker: missing precedence for partial data |
| 2026-01-08 | Added Dependencies section | Codex important: external dependencies not enumerated |
| 2026-01-08 | Added quantified baselines to Success Metrics | Codex enhancement: baselines not quantified |
| 2026-01-08 | Moved tech details to Implementation Notes appendix | Codex enhancement: keep PRD clean of tech details |

## Codex PLAN Review Summary (2026-01-08)

**Blockers Resolved:**
1. ✅ waitTimeFactorCache table usage - Added repository methods and job tasks for read/write
2. ✅ Phase 2/3 sequencing - Added interface contracts in Phase 1 to enable calculator mocking

**Important Issues Resolved:**
- ✅ Data quality/outlier logging - Added tests and implementation tasks per SDD contract
- ✅ Timezone handling tests - Added dayOfWeek conversion tests
- ✅ Mobile API integration test - Added endpoint verification

**Enhancements Applied:**
- ✅ Risks & Mitigations section added
- ✅ Definition of Done added to each phase
- ✅ Check-in flow regression test added

**Task Count Impact:**
- Original: 153 tasks
- After review: 174 tasks (+21 tasks)
- New tasks fill SDD coverage gaps and improve risk mitigation

---

## Codex PRD Review Summary (2026-01-08)

**Blockers Resolved:**
1. ✅ Conflicting data thresholds → Unified to "50 transactions in rolling 30-day window"
2. ✅ "Actual wait time" undefined → Added precise definition with timestamp sources and edge cases
3. ✅ Queue depth scope ambiguous → Added explicit inclusion/exclusion rules by status
4. ✅ Missing factor combination precedence → Added Factor Combination Rules section

**Important Issues Resolved:**
- ✅ Vague acceptance criteria → Added concrete thresholds (0.5-2.0 bounds, 24h TTL, etc.)
- ✅ Employee efficiency fallback undefined → Added 4-step precedence order
- ✅ Missing Dependencies section → Added external systems and internal data sources

**Enhancements Applied:**
- ✅ Technical details moved to appendix
- ✅ Baselines quantified in KPI table
- ✅ Typo "walkways" → "walkaways" fixed
- ✅ Business impact estimate added (NPS lift 5-10 points)

## Codex SDD Review Summary (2026-01-08)

**Blockers Resolved:**
1. ✅ PRD Feature 5 (Prediction Accuracy Logging) now fully designed
   - Added `actualMinutes` column to `waitTimePredictions` table
   - Added `waitTimeAccuracyDaily` aggregation table
   - Added `ActualWaitTimeBackfillJob` and `DailyAccuracyAggregationJob`
   - Added `AccuracyDataRetentionJob` for 12-month pruning
2. ✅ PRD edge-case handling codified
   - Added `Actual Wait Time Calculation Contract` with explicit rules
   - Abandoned, canceled, on_hold exclusions specified
   - Invalid timestamp handling and 480-minute cap documented
3. ✅ Time slot expansion (30-49 transactions) implemented
   - Added `EXPANSION_THRESHOLD` constant
   - Added `getHistoricalAverageByExpandedSlot()` method
4. ✅ Queue depth filters explicitly specified
   - Added `Queue Depth Query Contract` with exact SQL

**Important Issues Resolved:**
- ✅ Efficiency factor formula clarified (ADR-6 added)
- ✅ WhenIWork fallback precedence clarified with detailed comments
- ✅ Security considerations section added
- ✅ Performance budget for aggregation jobs documented

**Enhancements Applied:**
- ✅ Test scenarios expanded (9 scenarios, up from 4)
- ✅ PRD Edge Case Test Matrix added
- ✅ Test coverage table expanded with new components

**Architecture Decisions Confirmed:**
- ADR-1: Separate Service Layer ✅
- ADR-2: Redis for Factor Caching ✅
- ADR-3: Multiplicative Factor Combination ✅
- ADR-4: Nightly Cache Refresh ✅
- ADR-5: Employee Efficiency Precedence ✅
- ADR-6: Efficiency Factor Application Method ✅ (Apply as DIVISOR confirmed)

## Context

**Source Analysis**: [docs/analysis/wait-time-prediction-analysis.md](../../analysis/wait-time-prediction-analysis.md)

**Focus**: Quick win improvements to wait time prediction using PHP and smart data aggregation.

**Scope**: Implement the 4 quick wins identified in analysis:
1. **Dynamic Wait Time Factor by Hour/Day** - Use historical heatmap data to auto-adjust
2. **Queue Depth Multiplier** - Account for congestion in estimates
3. **Rolling Average Calibration** - Auto-calibrate `minutesPerContainer` weekly
4. **Employee Efficiency Weighting** - Factor in on-duty staff efficiency

**Expected Outcome**: Reduce MAPE from ~35-40% to ~25-30% (10-15% improvement)

**Out of Scope**: ML microservices, Python training jobs, real-time ML inference

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