Feature Specification: Onboarding Workflows

1. Overview & Vision

The Onboarding Workflow automates the transition from "New Hire" to "Productive Employee". It provides structured, role-based checklists that guide both the hire and their manager through the first 30-60-90 days, ensuring consistent cultural and operational alignment.

2. Personas & Stakeholders

Persona	Goal
New Hire	Complete assigned tasks, find internal resources, and learn company norms.
Manager	Monitor hire progress and verify task completion.
HR Admin	Design standard templates and audit onboarding success across the org.

3. User Stories

• As a new hire, I want a list of tasks for my first week so I don't feel lost on my first day.
• As an HR Admin, I want to create an "Engineering" template that includes setting up a GitHub account.
• As a manager, I want to see which of my hires are falling behind on their training tasks.

4. Functional Requirements (FR)

• REQ-ON-001: Role-based checklist templates (e.g., General, Technical, Sales).
• REQ-ON-002: Automated checklist generation upon employee record creation.
• REQ-ON-003: Timestamped completion tracking for individual tasks.
• REQ-ON-004: Support for task descriptions, links, and file attachments.
• REQ-ON-005: Magic Link portal — candidate self-submits bank account, tax ID, and identity documents via a secure time-limited link (no Shell account required).
• REQ-ON-006: HR side-by-side review — submitted candidate data presented alongside offer details for verification and confirmation.
• REQ-ON-007: Candidate management — create candidates without a Shell account; auto-link to Shell user on first login by email match.
• REQ-ON-008: First-login guide shown to employees in Probation status to orient them before full access is granted.

5. Non-Functional Requirements (NFR)

• Scalability: System MUST support cloning templates with 50+ tasks in < 1 second.
• Reliability: Checklists MUST be generated even if the employee is created via bulk import.

6. Business Logic & Rules

• Template Matching: Uses roleTag or departmentId to select the most relevant template.
• Task Ownership: Most tasks are completed by the hire; some are "Verification" tasks for the manager.
• Progress Calculation: Overall progress % = (Completed Tasks / Total Tasks) * 100.
• Magic Link Expiry: Self-submission links expire after 72 hours; HR can regenerate.
• Auto-Link: When a candidate logs in for the first time, HRM matches by email and links their Shell userId to the existing candidate record.
• Probation Gate: Shell fires a first-login guide event for employees whose lifecycle state is Probation.

7. User Interface (UI/UX)

• Progress Dashboard: Circular progress charts for the manager.
• Checklist View: Grouped by "Day 1", "Week 1", "Month 1".
• Interaction: One-click completion with optimistic UI updates.

8. Information Architecture

• "Onboarding" tab within the Employee Profile.
• "Onboarding Admin" section for HR administrators.

9. Data Model & Persistence

• Tables: onboarding_templates, onboarding_template_tasks, onboarding_checklists, checklist_items.

10. API & Service Layer

• GET /onboarding/checklists/:employeeId
• POST /onboarding/checklists/:employeeId/items/:itemId/complete
• OnboardingService manages the template-to-instance cloning.

11. Integration Patterns

• Trigger: Listens for EMPLOYEE_CREATED events from the EmployeeService.
• Docs: Tasks can link directly to internal pages in the Document module.

12. Security & Permissions

• RBAC: onboarding:read for new hires; onboarding:manage for HR Admins.
• Visibility: Managers can only see checklists for their direct reports.

13. Error Handling & Resilience

• Template Missing: Fall back to a "Default General" template if no role match is found.
• Draft Mode: Templates MUST be published before they can be used for new hires.

14. Performance & Scalability

• Recursive cloning is performed within a database transaction.
• Large task lists use virtualized rendering in the UI.

15. Globalization & i18n

• Support for localized task names and descriptions.

16. Accessibility (a11y)

• Accessible checkboxes with large click targets.
• High-contrast progress bars.

17. Observability & Analytics

• Tracking of "Time to Completion" for onboarding milestones.
• Analytics on "Most Skipped Tasks" to identify irrelevant content.

18. Testing & Quality

• Integration tests for the automatic cloning logic.
• E2E testing of the manager verification flow.

19. Constraints & Assumptions

• Assumes templates are pre-defined by HR Admins before hiring begins.

20. Future Enhancements

• Video training integration.
• Conditional tasks (e.g., "If laptop is Mac, do X; if Windows, do Y").