# Referral Onboarding Experiment — Task Breakdown

> Each task targets 1–2 working days. Copy each into the Notion task DB using the task page template. Set all statuses to `Not Started`, relate to the spec and implementation plan pages.

---

## Phase 1: Foundation

### Task 1 — Implement referral attribution resolver at onboarding entry

**Context:** Referred users need to be reliably identified before the first onboarding screen so downstream experiment logic has a clean signal.

**Objective:** Wire referral attribution (deep link params / invite code) into the onboarding entry point and expose a boolean `isReferred` flag to the onboarding flow.

**Acceptance Criteria:**
- [ ] Deep link and invite-code query param are parsed on onboarding load
- [ ] `isReferred` flag is set and available to downstream consumers
- [ ] Unresolved attribution is logged with reason for observability
- [ ] Unit tests cover: valid deep link, valid invite code, missing params, malformed input

**Dependencies:**
- Upstream: Confirm attribution data contract with growth/backend
- Cross-team: None
- Data/analytics: None yet

**Estimate:** 1 day

---

### Task 2 — Add experiment bucket assignment and persistence

**Context:** Referred users must be deterministically assigned to control or variant, and that assignment must survive app restarts and login transitions.

**Objective:** Integrate with the experiment framework to assign and persist a bucket for the referral onboarding experiment, gated behind a feature flag.

**Acceptance Criteria:**
- [ ] Experiment assignment occurs only for users where `isReferred = true`
- [ ] Assignment is deterministic (same user → same bucket on repeat visits)
- [ ] Assignment persists across sessions and logged-out → logged-in transition
- [ ] Feature flag defaults to OFF; when OFF, all users get control flow
- [ ] Unit tests cover: assignment, persistence, flag-off fallback, non-referred users excluded

**Dependencies:**
- Upstream: Task 1 (attribution resolver)
- Cross-team: Platform eng — confirm experiment framework API
- Data/analytics: None yet

**Estimate:** 1.5 days

---

## Phase 2: Experiment Launch

### Task 3 — Build variant onboarding UI flow

**Context:** The variant flow introduces referral-specific screens and copy to reinforce social proof during onboarding.

**Objective:** Implement the variant onboarding screens, navigation, and copy as specified in the design spec, rendered when the user is bucketed into the variant group.

**Acceptance Criteria:**
- [ ] Variant screens render with correct copy, layout, and assets
- [ ] Referrer name/context displayed where available; graceful fallback when missing
- [ ] Navigation between steps matches spec (back, skip, continue)
- [ ] Control group users see zero changes to existing flow
- [ ] Renders correctly on target platforms / screen sizes

**Dependencies:**
- Upstream: Task 2 (bucket assignment)
- Cross-team: Design/content — final copy and assets
- Data/analytics: None yet

**Estimate:** 2 days

---

### Task 4 — Instrument exposure and conversion funnel events

**Context:** The experiment is meaningless without clean event data. Every key moment in the onboarding funnel needs to be tracked for both control and variant.

**Objective:** Fire analytics events for experiment exposure, each onboarding step completion, final conversion, and drop-off, with correct properties and schema.

**Acceptance Criteria:**
- [ ] `referral_onboarding_exposed` event fires once per user on first onboarding screen load (includes bucket, referral channel)
- [ ] `referral_onboarding_step_completed` fires per step (includes step name, bucket, duration)
- [ ] `referral_onboarding_converted` fires on final onboarding completion
- [ ] `referral_onboarding_dropped` fires on exit/abandon (includes last completed step)
- [ ] All events validated in staging with correct property values
- [ ] Schema reviewed and approved by data eng

**Dependencies:**
- Upstream: Task 3 (variant UI) for variant-specific events; control events can start in parallel
- Cross-team: Data eng — schema review
- Data/analytics: Agree on event naming and property contract

**Estimate:** 1.5 days

---

### Task 5 — QA checklist and end-to-end validation

**Context:** Both paths (control and variant) need to be verified before any production ramp.

**Objective:** Execute a full QA pass covering both experiment arms, edge cases, and instrumentation correctness.

**Acceptance Criteria:**
- [ ] Control path: no regressions, no new events leak when flag is OFF
- [ ] Variant path: all screens, copy, navigation, and events verified
- [ ] Edge cases tested: missing referrer info, session expiry mid-flow, logged-out → logged-in, non-referred user hitting variant URL
- [ ] Instrumentation verified in staging (events appear in analytics tool with correct properties)
- [ ] QA sign-off documented

**Dependencies:**
- Upstream: Tasks 3 + 4
- Cross-team: QA / product review
- Data/analytics: Staging pipeline available

**Estimate:** 1 day

---

## Phase 3: Stabilization & Ramp

### Task 6 — Build experiment monitoring dashboard

**Context:** The team needs real-time visibility into experiment health during the staged rollout.

**Objective:** Create a dashboard (or saved query) showing exposure count, completion rate by bucket, drop-off by step, and error rate.

**Acceptance Criteria:**
- [ ] Dashboard shows: exposure count, completion rate (control vs variant), drop-off by step, error rate
- [ ] Data refreshes within acceptable latency (< 1h)
- [ ] Dashboard link added to implementation plan and spec pages

**Dependencies:**
- Upstream: Task 4 (events flowing)
- Cross-team: Data eng — confirm pipeline and table availability
- Data/analytics: Query access

**Estimate:** 0.5 days

---

### Task 7 — Staged rollout and rollback runbook

**Context:** Production ramp needs to be deliberate with clear criteria for advancing or rolling back.

**Objective:** Execute the staged rollout (5% → 25% → 50% → 100%) and document the rollback runbook.

**Acceptance Criteria:**
- [ ] Rollback runbook documented: trigger criteria, kill-switch steps, owner, communication plan
- [ ] Rollback tested in staging before first production ramp
- [ ] Each ramp stage held for 24h minimum; advance only if no regression triggers hit
- [ ] On-call team briefed on rollback procedure
- [ ] Final ramp to 100% confirmed with product + eng manager sign-off

**Dependencies:**
- Upstream: Task 5 (QA sign-off), Task 6 (dashboard live)
- Cross-team: On-call / SRE awareness
- Data/analytics: Dashboard operational

**Estimate:** 1 day (spread across ramp stages)

---

## Summary

| # | Task | Phase | Estimate | Depends On |
|---|------|-------|----------|------------|
| 1 | Implement referral attribution resolver | 1 | 1d | — |
| 2 | Add experiment bucket assignment + persistence | 1 | 1.5d | T1 |
| 3 | Build variant onboarding UI flow | 2 | 2d | T2 |
| 4 | Instrument exposure and conversion funnel events | 2 | 1.5d | T3 (partial parallel) |
| 5 | QA checklist and end-to-end validation | 2 | 1d | T3, T4 |
| 6 | Build experiment monitoring dashboard | 3 | 0.5d | T4 |
| 7 | Staged rollout and rollback runbook | 3 | 1d | T5, T6 |
| | **Total** | | **~8.5d** | |