# Product Requirements Document ## Validation Checklist - [x] All required sections are complete - [x] No [NEEDS CLARIFICATION] markers remain - [x] Problem statement is specific and measurable - [x] Problem is validated by evidence (not assumptions) - [x] Context → Problem → Solution flow makes sense - [x] Every persona has at least one user journey - [x] All MoSCoW categories addressed (Must/Should/Could/Won't) - [x] Every feature has testable acceptance criteria - [x] Every metric has corresponding tracking events - [x] No feature redundancy (check for duplicates) - [x] No contradictions between sections - [x] No technical implementation details included - [x] A new team member could understand this PRD --- ## Product Overview ### Vision Every shift has a clearly assigned role so employees know exactly what they're responsible for, and managers can precisely control who fills what position regardless of an employee's overall capabilities. ### Problem Statement Currently, when two employees who both hold the "Shift Lead" position are scheduled for the same time block, there is no way to specify that only one of them should act as Shift Lead while the other works as a Buyer. The system treats the employee's position assignment as a static property rather than a per-shift attribute. This causes: 1. **Role ambiguity**: When multiple people with the same position overlap, neither they nor the manager know who is actually filling that role for the shift 2. **Inaccurate scheduling**: The schedule calendar shows the employee's default position rather than their assigned role for that specific shift, leading to confusion during handoffs 3. **No clock-in context**: When employees clock in, they receive a generic success message with no information about their role or what tasks they should focus on, requiring them to find a manager or check a separate system These issues result in wasted time at shift start (employees asking managers what they're doing), scheduling misunderstandings, and difficulty holding people accountable to specific roles. ### Value Proposition This feature turns the clock-in moment into a productive briefing: employees immediately see their assigned role and tasks for the day. Managers get precise control over who does what per shift, not just per employee. The result is faster shift starts, clearer accountability, and reduced confusion when employees with overlapping skills are scheduled together. ## User Personas ### Primary Persona: Store Manager - **Demographics:** 25-45, manages daily store operations, moderate technical expertise, uses the scheduling system daily - **Goals:** Create schedules where each shift has a specific role assigned; ensure the right people are in the right roles even when multiple qualified employees overlap; reduce time spent explaining daily roles at shift start - **Pain Points:** Cannot differentiate between two Shift Leads on the same day; has to verbally communicate role assignments at shift start; no system-level record of who was assigned what role for a given shift ### Secondary Personas #### Shift Lead / Senior Employee - **Demographics:** 20-35, has multiple position qualifications (e.g., Shift Lead + Buyer), works 4-5 shifts per week - **Goals:** Know what role they're filling before arriving or immediately at clock-in; understand their tasks for the day without needing to ask a manager - **Pain Points:** Shows up not knowing if they're leading the shift or just buying; has to track down a manager to learn daily assignment; no single place to see role + tasks together #### General Employee - **Demographics:** 18-30, typically has 1-2 position qualifications, part-time or full-time - **Goals:** Clock in and immediately see what's expected of them; feel clear about their responsibilities - **Pain Points:** Generic clock-in message provides no daily context; has to look at multiple places (schedule, task board) to understand their shift ## User Journey Maps ### Primary User Journey: Manager Creates a Shift with Specific Role 1. **Awareness:** Manager realizes two Shift Leads are both scheduled for Tuesday — needs to designate which one actually leads 2. **Consideration:** Manager opens the scheduling page and creates or edits the shift 3. **Adoption:** The shift creation/edit form shows a "Position" dropdown populated with positions the employee is qualified for 4. **Usage:** - Manager selects "Buyer" for one Shift Lead and "Shift Lead" for the other - System validates that the employee holds the selected position - Schedule displays each shift with its specific role and position color 5. **Retention:** Manager trusts the schedule reflects reality; employees clock in and see their correct role ### Secondary User Journeys #### Employee Clocks In and Sees Daily Briefing 1. **Awareness:** Employee arrives at the store for their shift 2. **Consideration:** Employee opens the workbook kiosk and selects their name 3. **Adoption:** Employee enters their PIN and clocks in 4. **Usage:** - After successful clock-in, instead of a generic toast, a confirmation screen appears - Screen shows: "Successfully Clocked In" with their assigned role (e.g., "Today's Shift: Shift Lead") - Below the role, any tasks assigned to the employee's position for today are listed - Employee reviews their role and tasks, then dismisses the screen 5. **Retention:** Employee starts their shift knowing exactly what to do; no manager interruption needed #### Manager Edits a Role on an Existing Shift 1. **Awareness:** Manager realizes they assigned the wrong role to a shift, or staffing changes require a role swap 2. **Consideration:** Manager opens the existing shift on the schedule 3. **Adoption:** Manager changes the position dropdown to a different role 4. **Usage:** - System validates the employee holds the new position - Shift updates with new role and color - If the employee has already clocked in for this shift, their active session remains unaffected (the change applies for record-keeping and task context) 5. **Retention:** Easy correction maintains accurate records ## Feature Requirements ### Must Have Features #### Feature 1: Position Selection During Shift Creation - **User Story:** As a manager, I want to assign a specific position to each shift so that I can control exactly what role each employee fills regardless of how many positions they're qualified for - **Acceptance Criteria:** - [ ] When creating a shift for an employee, a "Position" field is shown - [ ] The position dropdown is populated with only positions the selected employee is qualified for (from `employeeSchedulePositions`) - [ ] If the employee has only one position, that position is auto-selected - [ ] If the employee has multiple positions, the manager must select one (no default assumed) - [ ] The selected position is saved with the shift - [ ] For open shifts (no employee), the position dropdown shows all active positions #### Feature 2: Position Selection During Shift Editing - **User Story:** As a manager, I want to change the assigned position on an existing shift so that I can correct mistakes or adjust for changing needs - **Acceptance Criteria:** - [ ] When editing a shift, the "Position" field is shown with current position pre-selected - [ ] Dropdown is filtered to only positions the assigned employee is qualified for - [ ] Changing the position updates the shift record - [ ] If the employee is changed to someone who doesn't hold the current position, the position field is cleared and must be re-selected #### Feature 3: Position Permission Validation - **User Story:** As a manager, I want the system to prevent assigning an employee to a position they don't hold so that scheduling errors are caught at creation time - **Acceptance Criteria:** - [ ] The system rejects shift creation/update if the selected positionId is not in the employee's assigned positions - [ ] A clear error message is shown: "Employee is not qualified for this position" - [ ] Validation occurs both on the frontend (dropdown filtering) and backend (API validation) - [ ] Open shifts (no employee assigned) are exempt from this validation #### Feature 4: Enhanced Clock-In Confirmation Screen - **User Story:** As an employee, I want to see my assigned role and daily tasks when I clock in so that I know exactly what I'm responsible for today - **Acceptance Criteria:** - [ ] After successful clock-in, a confirmation screen replaces the simple toast notification - [ ] The screen displays: "Successfully Clocked In" as the heading - [ ] Below the heading: "Today's Shift: [Position Name]" with the position color badge - [ ] Below the position: a list of tasks assigned to the employee's position for today (from the daily task assignment system) - [ ] If no position is assigned to the shift, the position line shows "No specific role assigned" - [ ] If no tasks are found, the tasks section shows "No tasks assigned for today" - [ ] The screen has a "Got it" / "Dismiss" button to close - [ ] The screen auto-dismisses after 15 seconds if not manually closed - [ ] For unscheduled clock-ins (manager override), the screen shows "Unscheduled Shift" instead of a position #### Feature 5: Schedule Display with Position Per Shift - **User Story:** As a manager, I want to see each shift's assigned position on the schedule calendar so that I can verify the right roles are covered - **Acceptance Criteria:** - [ ] Each shift on the schedule view shows the assigned position name and color - [ ] The position is displayed alongside the employee name on shift blocks - [ ] Shifts without an assigned position show no position badge (backward compatible) ### Should Have Features #### Feature 6: Position Color on Clock-In Confirmation - **User Story:** As an employee, I want to see my role displayed with its signature color so that it's immediately recognizable - **Acceptance Criteria:** - [ ] The position name on the clock-in confirmation is displayed with a colored badge matching the position's configured color - [ ] The color matches what managers see on the schedule calendar #### Feature 7: Task Completion Checklist on Clock-In Confirmation - **User Story:** As an employee, I want to see which tasks are already completed and which are pending when I clock in so I know what still needs to be done - **Acceptance Criteria:** - [ ] Tasks on the clock-in confirmation show completion status (checked/unchecked) - [ ] Completed tasks are visually distinguished (strikethrough or muted) - [ ] Task count summary shown: "3 of 7 tasks completed" ### Could Have Features #### Feature 8: Print/Share Daily Briefing - **User Story:** As an employee, I want to print or share my daily role + task list so I can reference it during my shift without returning to the kiosk - **Acceptance Criteria:** - [ ] A "Print" button on the clock-in confirmation allows printing the briefing - [ ] Print layout is optimized for a single page #### Feature 9: Position History Per Shift - **User Story:** As a manager, I want to see the history of position changes on a shift for accountability - **Acceptance Criteria:** - [ ] Shift audit log records position changes - [ ] Position change history is viewable in shift detail view ### Won't Have (This Phase) - **Auto-assignment of positions based on schedule optimization** — Position assignment remains manual; AI scheduling may suggest but not auto-assign positions in a future phase - **Position-based pay differential** — Different pay rates per position per shift is a future payroll feature - **WhenIWork position sync** — Position data from WhenIWork integration is displayed as-is; this feature applies to BuyerKiosk native scheduling only - **Task creation from clock-in screen** — The clock-in confirmation is read-only; task management stays on the dedicated task views - **Employee self-service role swaps** — Only managers can assign/change positions on shifts ## Detailed Feature Specifications ### Feature: Enhanced Clock-In Confirmation Screen **Description:** Replaces the current simple toast notification ("Successfully clocked in!") with a rich confirmation screen that serves as a daily briefing. The screen appears after a successful clock-in and shows the employee's assigned role for the shift and their position-relevant tasks for the day. **User Flow:** 1. Employee selects their name on the kiosk and enters PIN 2. Employee taps "Clock In" (optionally selecting a shift if multiple are available) 3. System processes the clock-in and creates the time punch record 4. Instead of a toast, a confirmation panel/modal appears with: - Success message and clock-in time - Shift position with color badge - Shift time range (e.g., "9:00 AM - 5:00 PM") - Task list for the employee's position today 5. Employee reviews and taps "Got it" to dismiss (or screen auto-dismisses after 15 seconds) 6. The normal kiosk state reloads showing "Clocked In" status **Business Rules:** - Rule 1: The clock-in confirmation data comes from the same clock-in API response — no additional API calls needed from the frontend - Rule 2: Tasks shown are those assigned to the employee's shift position via the daily task assignment cascade (DailyTaskAssignmentService) - Rule 3: If the employee's shift has no positionId set, display "No specific role assigned" — do not fall back to the employee's default positions - Rule 4: For WhenIWork-provider stores, position display uses the position field from WhenIWork shift data (if available) - Rule 5: The confirmation screen only appears on clock-in, not on clock-out, break start, or break end (those remain as toast notifications) - Rule 6: For manager-override clock-ins (unscheduled), show "Unscheduled Shift" as the position and omit the task list **Edge Cases:** - Scenario 1: Employee has no shift scheduled (unscheduled clock-in with override) → Expected: Show "Unscheduled Shift" with no tasks listed - Scenario 2: Shift exists but has no position assigned → Expected: Show "No specific role assigned" and no tasks - Scenario 3: Position assigned but no tasks exist for that position today → Expected: Show the position but "No tasks assigned for today" in the tasks section - Scenario 4: Employee clocks in via manager override after the shift window → Expected: Show the matched shift's position and tasks (the override only affects the clock window validation, not the role display) - Scenario 5: Multiple shifts available and employee selects one → Expected: Show the position from the selected shift, not any other shift - Scenario 6: Auto-dismiss timer runs out → Expected: Screen dismisses gracefully and kiosk returns to normal clocked-in state ### Feature: Position Permission Validation During Shift Assignment **Description:** Ensures that when a manager assigns an employee to a shift with a specific position, the employee must have that position in their assigned positions list. This prevents scheduling errors where someone is assigned a role they're not qualified for. **User Flow:** 1. Manager opens shift creation or edit form 2. Manager selects an employee from the employee dropdown 3. Position dropdown populates with only positions the employee holds 4. Manager selects a position 5. System saves the shift with the validated position **Business Rules:** - Rule 1: When an employee is selected, the position dropdown must only show positions from the employee's `employeeSchedulePositions` records - Rule 2: When the employee is changed on an existing shift, if the current position is not in the new employee's positions, the position field is cleared - Rule 3: Backend validation must independently verify the employee holds the position (defense in depth — frontend filtering alone is insufficient) - Rule 4: Open shifts (employeeId = null) allow any active position to be selected - Rule 5: If an employee has exactly one position, it should be auto-selected for convenience **Edge Cases:** - Scenario 1: Manager selects employee, picks a position, then changes the employee to someone who doesn't have that position → Expected: Position field is cleared; manager must re-select - Scenario 2: Position is removed from an employee after a shift was created with that position → Expected: Existing shift is NOT retroactively changed; position remains on the historical shift record. Editing the shift would show a warning that the employee no longer holds the position - Scenario 3: No positions are assigned to the selected employee → Expected: Position dropdown is empty with a message "No positions assigned to this employee — assign positions in Team Members" ## Success Metrics ### Key Performance Indicators - **Adoption:** Within 4 weeks, 80%+ of newly created shifts in stores using BuyerKiosk native scheduling have a position explicitly assigned - **Engagement:** Average clock-in confirmation screen view duration > 3 seconds (indicates employees are reading their briefing) - **Quality:** Zero position validation bypass incidents (no shifts saved where the employee lacks the assigned position) - **Business Impact:** 50% reduction in "what am I doing today?" questions at shift start (measured via manager survey after 30 days) ### Tracking Requirements | Event | Properties | Purpose | |-------|------------|---------| | `shift.created` | `hasPosition: bool, positionId, employeeId` | Track position assignment adoption during shift creation | | `shift.updated` | `positionChanged: bool, oldPositionId, newPositionId` | Track position edit frequency | | `shift.position_validation_failed` | `employeeId, positionId, reason` | Monitor validation catches to confirm feature value | | `clockin.confirmation_shown` | `employeeId, positionId, positionName, taskCount, shiftId` | Track clock-in briefing display | | `clockin.confirmation_dismissed` | `employeeId, dismissMethod: 'manual' or 'auto', viewDurationMs` | Measure engagement with the briefing screen | | `clockin.confirmation_task_viewed` | `employeeId, taskId` | Track if employees interact with task list | --- ## Constraints and Assumptions ### Constraints - Must work within existing BuyerKiosk native scheduling infrastructure (scheduleShifts table already has positionId column) - Clock-in confirmation must not add additional API calls — all data should be included in the existing clock-in response - Must be backward compatible: existing shifts without positions should continue to work normally - Feature applies to BuyerKiosk scheduling provider only; WhenIWork integration displays whatever position data WhenIWork provides - The kiosk is a shared terminal — the confirmation screen must be dismissed before another employee can use it ### Assumptions - Employees have positions assigned via the Team Members page (`employeeSchedulePositions` junction table) - The DailyTaskAssignmentService (from the task system) can resolve tasks by position for a given date - Managers creating shifts have `uri_schedule_manage` permission - The existing `positionId` column on `scheduleShifts` is currently optional and sparsely populated — this feature makes it a prominent part of the workflow without making it required ## Risks and Mitigations | Risk | Impact | Likelihood | Mitigation | |------|--------|------------|------------| | Employees don't have positions assigned, making position dropdown empty | High | Medium | Show helpful message linking to Team Members page; add position assignment prompt to employee onboarding flow | | Confirmation screen slows down clock-in for employees in a rush | Medium | Low | Auto-dismiss after 15 seconds; "Got it" button is prominent and immediate; screen is non-blocking to the clock-in record itself | | Existing shifts without positions look broken after update | High | Low | Backward compatible — shifts without positions display exactly as they do today; no position badge shown | | Large number of tasks clutters the confirmation screen | Low | Low | Limit display to first 10 tasks with "and X more..." link; tasks are already organized by group | | Manager forgets to assign a position when creating a shift | Medium | Medium | Show a visual prompt or soft warning (not a hard requirement) when creating a shift without a position selected | ## Open Questions All open questions have been resolved during the specification process: - [x] Should position assignment be required when creating a shift? → **No, it remains optional for backward compatibility. A soft prompt/warning is shown but not enforced.** - [x] Should the clock-in confirmation be a modal or an inline expansion? → **A panel/modal overlay within the existing clock-in modal to maintain kiosk flow.** - [x] Should the auto-dismiss timer be configurable per store? → **No, 15 seconds is fixed for simplicity. Can be made configurable later if feedback warrants it.** - [x] What happens when an employee is qualified for many positions (10+)? → **The dropdown shows all positions; list is scrollable. Positions are sorted by sortOrder from schedulePositions.** --- ## Supporting Research ### Competitive Analysis Scheduling platforms like WhenIWork, Homebase, and 7shifts all support per-shift position assignment. WhenIWork maps positions to shifts and shows position names on the calendar. 7shifts goes further with position-based labor cost projections. This feature brings BuyerKiosk native scheduling to parity with these platforms on role specificity. ### User Research Direct user feedback indicates that multi-qualified employees (especially Shift Leads who can also Buy) frequently start shifts unsure of their role for the day. Managers report spending 5-10 minutes at each shift change verbally communicating role assignments. The clock-in briefing concept was specifically requested by store managers who want employees to "hit the ground running." ### Market Data Workforce management industry trend toward "shift-level role assignment" as stores move away from fixed roles. Research shows that clear role communication at shift start correlates with higher employee satisfaction and reduced first-hour productivity loss.