# OSHUN North-Star Metrics and Activation Funnel

Status: Draft v1.0 Owner: OSHUN Product + Data + Engineering Last Updated: March
22, 2026 Related: `docs/releases/v1/specs/product-brief.md`,
`docs/releases/v1/scope/mvp-scope.md`, `docs/releases/v1/specs/personas.md`,
`docs/releases/v1/specs/program-charter.md`

## 1. Purpose

This document defines:

- OSHUN north-star metrics
- Supporting KPI hierarchy
- Activation funnel design
- Event instrumentation requirements

The goal is to measure if OSHUN is delivering durable cross-domain value, not
just app opens.

## 2. Measurement Principles

1. Value over vanity: prioritize completed high-value actions, not raw traffic.
2. Cross-domain health: measure engagement across Tara, Arete, Veritas, Nyx, and
   Nisaba.
3. Retention-first: improve repeat value, not one-time novelty.
4. Comparable definitions: same metric semantics across mobile, web, and PWA.
5. Privacy-aware telemetry: only consented analytics events in KPI computation.

## 3. North-Star Metric

### 3.1 Primary North-Star

Cross-Domain Weekly Value Users (CD-WVU)

Definition:

- Unique users who complete >= 2 value actions across >= 2 distinct domains
  within a rolling 7-day window.

Why this metric:

- Reflects OSHUN's core promise: one shell, meaningful multi-domain value.
- Captures both engagement depth and cross-domain breadth.
- Correlates better with retention and subscription potential than DAU alone.

Formula:

- `CD-WVU = COUNT(DISTINCT user_id)` where user meets:
  - `distinct_domains_with_value_action >= 2`
  - `total_value_actions_7d >= 2`

### 3.2 Domain Value Actions (MVP)

- Tara: meditation launch or resume completion event
- Arete: daily check-in completion event
- Veritas: verified story/claim open completion event
- Nyx: nightly highlight or exploration completion event
- Nisaba: passage open, study continuation, or annotation completion event

## 4. Supporting KPI Stack

### 4.1 Tier 1: Product Health KPIs

- DAU, WAU, MAU
- D1, D7, D30 retention
- CD-WVU ratio to WAU
- Crash-free session rate
- p95 home hydration latency

### 4.2 Tier 2: Activation and Habit KPIs

- New user activation rate (A0->A3)
- Time-to-first-value (TTFV)
- Week-1 repeat value action rate
- Save-to-return conversion rate
- Notification opt-in quality rate

### 4.3 Tier 3: Domain KPIs

- Tara: session starts, completions, resume rate
- Arete: daily check-in completion, streak stability, recovery-after-miss rate
- Veritas: verification drill-down completion, save/follow conversion
- Nyx: nightly highlight engagement, exploration completion
- Nisaba: passage open rate, annotation rate, study-return rate

## 5. Activation Funnel

### 5.1 Funnel Stages

- A0: Install/Open
- A1: Account Created or Sign-In Completed
- A2: Profile/Preferences Initialized
- A3: First Domain Value Action Completed
- A4: Second Value Action Completed (same or different domain)
- A5: Cross-Domain Value Achieved (>=2 domains in first 7 days)

### 5.2 Funnel Definitions

A0 -> A1:

- User successfully authenticates and receives valid session.

A1 -> A2:

- User completes core setup:
  - notification preference set
  - theme or personalization preference set

A2 -> A3:

- User completes first value action in any domain.

A3 -> A4:

- User completes a second value action within 72 hours.

A4 -> A5:

- User completes a value action in a second domain within 7 days.

### 5.3 Activation Success Targets (Initial)

- A0 -> A1 >= 60%
- A1 -> A2 >= 75%
- A2 -> A3 >= 65%
- A3 -> A4 >= 50%
- A4 -> A5 >= 35%

Notes:

- Targets are initial planning thresholds and should be re-baselined after first
  production cohorts.

## 6. Retention Funnel

- R1: Returned in Day 1 (any meaningful session)
- R7: Returned in Day 7 with >=1 value action
- R30: Returned in Day 30 with >=1 value action
- R30-CD: Returned in Day 30 with >=2 domains engaged in prior 30 days

Primary retention focus:

- Increase R7 and R30-CD, not only raw return rate.

## 7. Event Instrumentation Spec (MVP)

### 7.1 Required Core Events

- `oshun.app_opened`
- `oshun.auth_completed`
- `oshun.profile_initialized`
- `oshun.domain_card_opened`
- `oshun.value_action_completed`
- `oshun.item_saved`
- `oshun.item_resumed`
- `oshun.search_executed`
- `oshun.notification_opened`

### 7.2 Required Event Properties

- `user_id` or privacy-preserving stable identifier
- `session_id`
- `platform` (`ios`, `android`, `web`, `pwa`)
- `domain` (`tara`, `veritas`, `nyx`, `arete`, `oshun_shell`)
- `timestamp` (ISO8601)
- `event_version`
- `consent_analytics` boolean

### 7.3 Value Action Normalization

`oshun.value_action_completed` must include:

- `value_action_type` (domain-specific normalized action)
- `domain`
- `completion_quality` (`partial`, `full`)
- `content_id` or `entity_id` where applicable

## 8. Dashboard Requirements

### 8.1 Executive Dashboard

- CD-WVU trend (7d/30d)
- Activation funnel conversion by stage
- D1/D7/D30 retention trend
- Cross-domain engagement distribution

### 8.2 Product Operations Dashboard

- TTFV p50/p95
- Home feed latency and error rates
- Domain launch success/failure by platform
- Save-to-return conversion trend

### 8.3 Domain Dashboards

- Tara, Arete, Veritas, Nyx, Nisaba value action trends
- Domain-specific funnel drop-offs
- Domain contribution to CD-WVU

## 9. Alert Thresholds (Initial)

- CD-WVU drops > 15% week-over-week
- A2 -> A3 conversion drops > 20% week-over-week
- R7 drops > 10% week-over-week
- value action event ingestion failure rate > 2%
- p95 home hydration latency > 2.5s for 3 consecutive 15-min windows

## 10. Data Quality Rules

- Ignore events without consent for analytics views.
- Deduplicate idempotent events using `event_id` + 5-minute window policy.
- Validate domain enum and value action enum.
- Reject events missing `timestamp`, `platform`, or identifier fields.
- Backfill policy must tag replayed events with `is_backfill=true`.

## 11. Experimentation and Review Cadence

- Weekly: activation and retention review with product/engineering.
- Bi-weekly: experiment readouts and KPI impact summary.
- Monthly: metric definition audit and event quality health check.
- Quarterly: north-star validity review and threshold recalibration.

## 12. Ownership

- Product: KPI strategy and prioritization decisions
- Engineering: instrumentation correctness and pipeline reliability
- Data/Analytics: metric computation, dashboard governance, and anomaly analysis
- Domain teams: value action contract integrity per domain
