> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention & Lifecycle

> Move beyond acquisition — read the retention lens (churn, resubscribe, churn split), detect churn spikes, and propose gated winback campaigns.

# Retention & Lifecycle

Most of the co-founder's signals are acquisition-biased — ASO, ads, keyword
ranks, reviews. But keeping users matters as much as getting them. This
capability gives the agent a **retention lens** on your subscription data, a
**churn-spike crisis mode**, and a way to **act** on churn via gated winback
campaigns.

## The retention lens

Each run, the agent composes a `retention` block from data it already collects —
no extra setup:

* **Churn** — latest daily churn vs the 30-day baseline (Apple ASC; RevenueCat
  fills in cross-platform churn when connected).
* **Resubscribe rate** — reactivations ÷ cancellations over 30 days.
* **Trial→paid conversion**.
* **Churn split** — voluntary cancels vs involuntary (billing retries / expiry)
  vs refunds. This matters: *involuntary* churn is a billing/dunning fix (grace
  periods, retry config), while *voluntary* churn is a value/pricing/onboarding
  fix. The agent treats them differently.

The block is code-computed (not guessed by the LLM) and written onto every
report. You see it on the co-founder hub (a **Retention** panel) and on each
report's **Retention** section — with a churn-spike banner when one fires.

## Churn-spike crisis mode

The retention twin of [reviews crisis mode](./reviews-crisis-mode). When the latest
daily churn runs well above your 30-day baseline (with an absolute floor and a
minimum subscriber base so tiny numbers don't cry wolf), the agent:

1. Flags a **CHURN SPIKE** in the briefing with the numbers and likely causes.
2. Emits a [`churn_spike` signal](../concepts/signals) so the event orchestrator
   schedules a focused run.
3. Proposes a winback `lifecycle_campaign` paired with the concrete
   monetization/product fix.

You can also run the [Why-agent](./why-agent) on `asc.churn` to get a root-cause
analysis of *why* users are leaving.

## Winback campaigns (`lifecycle_campaign`)

A `lifecycle_campaign` targets a **segment** (churned last 30d, trial-ending,
dormant) with a subject line, draft copy, and a suggested lever (e.g. a win-back
offering, a fixed onboarding step).

### Phase 1: owner brief (not an end-user blast)

The agent does **not** email your users directly. We don't have churned
end-users' email addresses or their marketing consent — RevenueCat identifies
customers by app-user-id, not email. So phase 1 sends **you** (the owner) a
ready-to-run winback brief via email: the segment, why now, the lever, and draft
copy you can send from your own ESP / push tool.

Direct end-user email, push (OneSignal / APNs / FCM), and in-app (RevenueCat
Customer Center) are **deferred to phase 2** — they require a subscriber list +
per-channel consent.

### Always gated

`lifecycle_campaign` is user-facing outbound messaging, so it **always**
requires your explicit approval — even at the highest autopilot level, and even
if you've added it to auto-approve types.

## The loop

1. **Read** — churn, resubscribe, churn split, trial conversion.
2. **Detect** — a churn spike fires a `churn_spike` signal + crisis callout.
3. **Diagnose** — optionally run the Why-agent on `asc.churn`.
4. **Act (gated)** — propose a winback `lifecycle_campaign`; you approve; the
   brief lands in your inbox.
5. **Measure** — the campaign is recorded as a `retention` experiment in memory
   (expected metrics: churn, active subscriptions, reactivations, MRR) and its
   outcome is reconciled after the measurement window.

## Requirements

* **Apple subscription metrics** (App Store Connect connected) for churn / flows,
  and/or **RevenueCat** for cross-platform churn.
* **Email configured on the server** (`RESEND_API_KEY` + `EMAIL_FROM_ADDRESS`)
  for the winback brief to actually send. Sends are always approval-gated.