# Referral Onboarding Experiment — Implementation Plan

## Plan Metadata
- Spec link: [Notion — Referral Onboarding Experiment (Approved)]
- Plan owner: [TBD — assign at sprint planning]
- Engineering manager: [TBD]
- Product partner: [TBD]
- Status: `Draft`
- Last updated: 2026-04-14

---

## 1. Feature Overview
- Problem and user impact: Referred users currently land in the same generic onboarding flow as organic signups. We lose the high-intent signal and miss the chance to reinforce the social proof that brought them in, leading to lower activation rates for this cohort.
- Business objective: Increase referred-user activation rate by running a controlled experiment with a tailored onboarding variant.
- Success metrics: Exposure count, onboarding completion rate (variant vs control), 7-day retention delta, referral-attributed conversion rate, drop-off rate per step.

## 2. Requirements Summary

### Must Have
- Detect referral attribution at onboarding entry (deep link / invite code resolution)
- Assign referred users to experiment buckets (control = existing flow, variant = new flow) with persistent assignment
- Build the variant onboarding UI flow with referral-specific copy and steps
- Instrument exposure, step-completion, conversion, and drop-off events
- Enforce rollout guardrails: feature flag gating, percentage ramp, kill-switch rollback path

### Should Have
- Support multiple copy variants (A/B on messaging) if product wants to test tone
- Surface referrer name/context in the variant flow where available
- Dashboard or saved query for real-time experiment monitoring

### Non-Goals
- Changes to the referral send/share flow (upstream of onboarding)
- Reward/incentive logic — handled by a separate team/spec
- Push notification or re-engagement campaigns for drop-offs

### Clarifications / Assumptions
- Assumption: Existing referral attribution (deep link params or invite code) is reliable at the point the onboarding screen loads. Validation owner: [backend / growth eng]. Needed by: Phase 1 start.
- Assumption: Experiment framework already supports persistent bucket assignment; no new infra needed. Validation owner: [platform eng]. Needed by: Phase 1 start.
- Assumption: Copy and design for the variant flow are finalized in the spec. Validation owner: [product/design]. Needed by: Phase 2 start.

---

## 3. Phased Delivery

### Phase 1: Foundation (Sprint N)
- Deliverables:
  - Referral attribution resolver wired into onboarding entry point
  - Experiment assignment + persistence logic behind feature flag
  - Unit tests for eligibility gate and bucket assignment
- Exit criteria:
  - Referred user reliably identified before first onboarding screen
  - Bucket assignment is deterministic and persisted across sessions
  - Feature flag defaults OFF in production
- Dependencies:
  - Confirm attribution data contract with growth/backend
  - Confirm experiment framework API with platform team

### Phase 2: Experiment Launch (Sprint N / N+1)
- Deliverables:
  - Variant onboarding UI flow (screens, copy, navigation)
  - Exposure, step-completion, conversion, and drop-off event instrumentation
  - QA pass on both control and variant paths
- Exit criteria:
  - Variant flow renders correctly on target platforms
  - All events fire with correct properties (verified in dev/staging)
  - QA sign-off checklist complete
- Dependencies:
  - Final copy and assets from design/content
  - Analytics schema review from data eng

### Phase 3: Stabilization & Ramp (Sprint N+1)
- Deliverables:
  - Monitoring dashboard or saved query for key metrics
  - Staged rollout: 5% → 25% → 50% → 100%
  - Rollback runbook documented
- Exit criteria:
  - No error-rate regression at each ramp stage
  - Experiment data flowing and queryable within 24h of first ramp
  - Rollback successfully tested in staging
- Dependencies:
  - Data eng confirms pipeline latency is acceptable
  - On-call aware of rollback trigger

---

## 4. Dependencies and Risks

| Dependency / Risk | Mitigation | Owner |
|---|---|---|
| Attribution data may be missing for some referral channels | Add fallback check (invite code query param); log unresolved rate | Backend / Growth |
| Experiment framework edge cases (e.g., logged-out → logged-in transition) | Spike during Phase 1; document assignment contract | Platform Eng |
| Copy/design not finalized before Phase 2 | Placeholder copy behind flag; swap before ramp | Product / Design |
| Event schema disagreement delays instrumentation | Pre-align schema in Phase 1 kickoff | Data Eng / Growth |

---

## 5. Validation and Rollout
- Test plan: Unit tests (eligibility, bucketing), integration tests (full onboarding path for control + variant), manual QA checklist
- Instrumentation checks: Validate every event fires in staging with correct properties before ramp
- Rollout strategy: Feature-flag percentage ramp — 5% → 25% → 50% → 100%, with 24h soak at each stage
- Rollback trigger: >2% increase in onboarding error rate OR >10% drop in onboarding completion rate vs control baseline → kill-switch to 0%

---

## 6. Linked Execution
- Task database link: [Notion task DB — filter by `Referral Onboarding`]
- Tasks filtered by plan: see task list below
- Spec back-link added: `No` — add after plan is moved to Notion