# Feature PRD: Self-Serve Onboarding Checklist

## 1. Feature Name

Self-Serve Onboarding Checklist

## 2. Epic

- [Activation Epic PRD](../epic-prd.md)

## 3. Goal

- **Problem:** 62% of new self-serve sign-ups drop off before completing a single core workflow within 7 days. Median time-to-first-value is 4.3 days, while competitors average under 1 day. Users who complete at least 3 key setup steps within 48 hours retain at 3.2x the rate, but there is no structured guidance to drive them toward those steps. "Getting started" support tickets account for 34% of all new-user ticket volume.
- **Solution:** Provide a persistent, in-app checklist panel that appears immediately after sign-up and guides users through 5 essential setup and first-use actions. The checklist is lightweight (not a wizard), persists across sessions and devices via server-side state, and can be dismissed and re-accessed at will. Invited team members see a tailored shorter variant.
- **Impact:** Increase 7-day sign-up-to-first-value conversion from 38% to 60%. Reduce median time-to-first-value from 4.3 days to under 24 hours. Reduce "getting started" support tickets from 34% to under 15% of new-user volume. Lift 30-day retention for activated users from 71% to 78%.

## 4. User Personas

- **New Self-Serve User:** An individual contributor or small-team lead who signs up via the website without sales involvement. Typically non-technical or semi-technical. Needs to see value quickly or will churn. Has no existing organizational context in the platform.
- **Invited Team Member:** A user added to an existing account by an admin. Has organizational context (projects, team already exist) but is unfamiliar with the platform's interface and workflows. Needs a lighter onboarding path focused on personal setup and tool orientation rather than workspace bootstrapping.

## 5. User Stories

- As a **new self-serve user**, I want to see a clear list of setup steps after I sign up so that I know exactly what to do first.
- As a **new self-serve user**, I want to see my progress through the checklist so that I feel a sense of momentum and know how close I am to being fully set up.
- As a **new self-serve user**, I want to click a checklist item and be taken directly to the relevant part of the app so that I don't have to figure out where things are.
- As a **new self-serve user**, I want to dismiss the checklist temporarily so that it doesn't block me when I want to explore freely.
- As a **new self-serve user**, I want to re-open the checklist after dismissing it so that I can pick up where I left off.
- As a **new self-serve user**, I want to see a completion celebration when I finish all steps so that I feel rewarded for completing setup.
- As an **invited team member**, I want to see a shorter checklist tailored to my situation so that I'm not asked to do things my admin already handled.
- As an **invited team member**, I want to skip the checklist entirely if I prefer to explore on my own so that onboarding doesn't feel forced.

## 6. Requirements

### Functional Requirements

#### Checklist Panel

- Display a collapsible sidebar panel on the right side of the app after first sign-up/login.
- The panel contains a header ("Get Started"), a progress bar showing X of N steps completed, and the list of checklist items.
- Each checklist item shows: a checkbox icon (empty or checked), the step title, and a brief description (max 15 words).
- Clicking a checklist item navigates the user to the relevant page or opens the relevant modal (deep-link behavior).
- Items are automatically marked complete when the underlying action is detected (e.g., profile saved, project created), not when clicked.
- The panel is collapsible via a toggle button. When collapsed, a small floating badge shows remaining steps (e.g., "3/5").
- The panel re-expands automatically if the user has been inactive for 2+ minutes on the dashboard with incomplete steps (max once per session).
- The user can permanently dismiss the checklist via a "Dismiss checklist" option in the panel menu. Dismissal requires a single confirmation ("You can always find this in Settings > Onboarding. Dismiss?").

#### Checklist Items — New Self-Serve User (5 steps)

1. **Complete your profile** — Add your name, avatar, and role. Deep-links to Profile Settings.
2. **Create your first project** — Set up a project to organize your work. Deep-links to New Project flow.
3. **Invite a team member** — Collaborate by adding at least one teammate. Deep-links to Team Invite modal.
4. **Run your first report** — Generate a report to see your data in action. Deep-links to New Report flow.
5. **Connect an integration** — Link Slack, Jira, or GitHub to your workspace. Deep-links to Integrations page.

#### Checklist Items — Invited Team Member (3 steps)

1. **Complete your profile** — Add your name, avatar, and role.
2. **Run your first report** — Generate a report to see your data in action.
3. **Connect an integration** — Link Slack, Jira, or GitHub to your workspace.

(Skips "Create your first project" and "Invite a team member" since these are typically handled by the inviting admin.)

#### Completion Experience

- When all checklist items are marked complete, display a confetti animation and a congratulatory message ("You're all set! You've completed your workspace setup.").
- The panel auto-hides 5 seconds after the completion animation, or immediately on click.
- After completion, the checklist is accessible from Settings > Onboarding for reference but no longer surfaces proactively.

#### State Management

- Checklist state (item completion, dismissed, variant) must be stored server-side per user.
- State must sync across devices and browser sessions in real time.
- A REST API endpoint must support: reading checklist state, marking items complete, dismissing the checklist, and resetting the checklist (admin/support use only).

#### Feature Flagging & Rollout

- The feature must be gated behind a LaunchDarkly feature flag (`onboarding-checklist-v1`).
- The flag must support percentage-based rollout and targeting by user cohort (new sign-ups after flag-on date only).
- Users who signed up before the flag is enabled must not see the checklist retroactively.

#### Analytics

- Emit the following events to Segment (routed to Amplitude):
  - `onboarding_checklist_viewed` — when the panel is first displayed.
  - `onboarding_checklist_item_completed` — with `item_name` property, when each step is completed.
  - `onboarding_checklist_completed` — when all steps are marked done.
  - `onboarding_checklist_dismissed` — when the user permanently dismisses.
  - `onboarding_checklist_collapsed` / `onboarding_checklist_expanded` — on toggle.
- All events must include: `user_id`, `checklist_variant` (full | invited), `items_completed_count`, `timestamp`.

### Non-Functional Requirements

- Checklist panel must render within 200ms of page load (p95).
- Checklist state API calls must complete within 150ms (p95).
- Must meet WCAG 2.1 AA accessibility standards:
  - Panel must be keyboard-navigable (Tab through items, Enter to activate, Escape to collapse).
  - Screen readers must announce checklist item status ("Step 1 of 5: Complete your profile — not started" / "completed").
  - Color contrast must meet AA ratios; completion state must not rely on color alone (use icons).
- Panel must be responsive: renders as a bottom sheet on viewports under 768px.
- Checklist must gracefully degrade if the API is unavailable: show the panel with cached state if available, hide it entirely if not (no error UI shown to user).
- No new third-party dependencies. Must use existing design-system components.

## 7. Acceptance Criteria

- [ ] Given a new self-serve user signs up and logs in for the first time, When the dashboard loads, Then the onboarding checklist panel is visible on the right side with 5 unchecked items and a progress bar showing "0 of 5 complete."
- [ ] Given an invited team member logs in for the first time, When the dashboard loads, Then the onboarding checklist panel is visible with 3 unchecked items and a progress bar showing "0 of 3 complete."
- [ ] Given a user clicks the "Complete your profile" checklist item, When the click occurs, Then the user is navigated to the Profile Settings page.
- [ ] Given a user saves their profile with name, avatar, and role filled in, When the save completes, Then the "Complete your profile" item is automatically checked and the progress bar updates.
- [ ] Given a user has completed 3 of 5 items and closes the browser, When they log in again on any device, Then the checklist shows 3 of 5 items checked with the correct items marked complete.
- [ ] Given a user clicks the collapse toggle on the panel, When the panel collapses, Then a floating badge displays "X/5" (or "X/3" for invited variant) and an `onboarding_checklist_collapsed` event is emitted.
- [ ] Given a user selects "Dismiss checklist" from the panel menu, When they confirm dismissal, Then the panel is hidden, an `onboarding_checklist_dismissed` event is emitted, and the checklist is accessible from Settings > Onboarding.
- [ ] Given a user completes all checklist items, When the final item is marked complete, Then a confetti animation plays, a congratulatory message is displayed, and the panel auto-hides after 5 seconds.
- [ ] Given the checklist API is unavailable, When the page loads, Then the checklist panel does not render and no error is shown to the user.
- [ ] Given a user navigates via keyboard only, When they Tab to the checklist panel, Then they can navigate between items with Tab, activate items with Enter, and collapse the panel with Escape.
- [ ] Given the LaunchDarkly flag `onboarding-checklist-v1` is disabled, When any user logs in, Then the checklist panel does not render.
- [ ] Given a user who signed up before the feature flag was enabled, When they log in after the flag is enabled, Then the checklist panel does not render.

## 8. Out of Scope

- **Gamification beyond confetti:** Badges, points, leaderboards, or streak mechanics are not included in v1.
- **Customizable checklist items:** Admins cannot add, remove, or reorder checklist steps in v1. Items are hardcoded.
- **Onboarding for admin/settings pages:** The checklist covers core workflows only; admin configuration guidance is deferred.
- **A/B testing of checklist copy or ordering:** Will be handled post-launch via the experimentation platform.
- **Checklist analytics dashboard:** Events are tracked in Amplitude, but no custom dashboard is planned for v1.
- **Multi-language support:** Checklist copy is English-only in v1. i18n will follow in a subsequent release.
- **Re-onboarding or "what's new" flows:** The checklist is a one-time experience; re-engagement for returning users is handled by the Welcome Dashboard Widget (P2).