churn_analysis v1.0.0

name: churn_analysis description: Diagnoses customer churn: builds cohort retention tables, computes logo churn, gross and net revenue retention, designs exit surveys that yield usable reasons, and drafts win-back plays by segment. Triggers when someone asks why customers are leaving, what retention looks like by signup cohort, how to measure churn correctly, or how to win cancelled customers back.

Purpose

Churn is the leak every growth plan ignores. This skill measures it without lying to yourself, figures out which customers leave and why, then turns that into concrete win-back moves. It covers retention diagnostics only. For the pricing side of the business, see pricing-basics. For overall unit viability (CAC, LTV, payback), see unit-economics.

Workflow

1. Get the raw data. You need, per customer: signup date, plan or MRR at signup, current MRR, status (active, cancelled, downgraded), and cancellation date if applicable. Without this, stop and say so. Do not estimate from memory.
2. Build a cohort retention table. Group customers by signup month, then track what share is still active 1, 2, 3 ... N months later. The shape of the curve matters more than any single number: a steep month-1 drop is an onboarding problem, a steady bleed is a value problem, a cliff at month 12 is a renewal or annual-plan problem.
3. Compute the three numbers, separately, and never mix them:

• Logo churn = customers lost in period / customers at start of period.
• Gross revenue retention = (starting MRR - contraction MRR - churned MRR) / starting MRR. Expansion does not enter this number. Anything above 90 percent monthly or around that range is solid for SMB; below that, dig in.
• Net revenue retention (NRR) = (starting MRR + expansion MRR - contraction MRR - churned MRR) / starting MRR. NRR above 100 percent means the remaining customers are growing faster than the losses.

1. Segment before you conclude. Cut churn by plan tier, acquisition channel, company size, and first-month usage. One bad segment often hides inside a fine-looking average. Name the worst segment and its rate.
2. Run the exit survey right. Ask at cancellation, in the flow, one question first: "What is the main reason you are cancelling?" with 5-7 specific options plus a text box. Follow with: "What would have kept you?" Keep it under 4 questions. Collect at least 50 responses before trusting the ranking.
3. Draft the win-back play. Segment ex-customers into: left for price, left for missing feature, never onboarded, went to a competitor. Each gets a different move (discount window, feature-announcement note, white-glove re-onboard, competitive comparison). Write the timing too: most win-backs happen in the first 30 days after cancellation.

Cohort table calculator

Save the snippet below as cohort_table.py and run it with python3 cohort_table.py. Replace the sample records with your own data. The script was run locally and prints retention fractions per signup cohort, per month.

python
# cohort_table.py
# Usage: python3 cohort_table.py
# Input: list of (cohort, active_months) records, where cohort is a
# signup-month string and active_months is how many months that customer
# stayed active. Prints retention fractions per cohort, per month.
from collections import defaultdict

def cohort_table(records, months=6):
    cohorts = defaultdict(lambda: [0] * months)
    for cohort, active in records:
        for m in range(min(active, months)):
            cohorts[cohort][m] += 1
    table = {}
    for c in sorted(cohorts):
        size = cohorts[c][0]
        table[c] = [round(n / size, 3) if size else 0.0 for n in cohorts[c]]
    return table

if __name__ == "__main__":
    # Replace these records with your own customer data
    records = ([("2026-05", a) for a in [6, 6, 5, 4, 3, 3, 2, 1, 6, 5]]
             + [("2026-06", a) for a in [6, 5, 5, 4, 4, 3, 2, 2, 1, 5, 4]]
             + [("2026-07", a) for a in [4, 4, 3, 3, 2, 2, 1, 3]])
    for cohort, row in cohort_table(records).items():
        print(cohort, row)

Output Contract

Every churn analysis delivered by this skill must include:

• The cohort retention table (or a clear summary of its curve shape if the table is large).
• Logo churn, gross revenue retention, and NRR as three separate numbers with the period stated (monthly or annual).
• The worst segment named, with its churn rate and how it compares to the average.
• Top 3 cancellation reasons from exit data, with response counts. If fewer than 50 responses exist, label the ranking as preliminary.
• One win-back play per churn segment, each with the target segment, the offer or message, and the timing.

Operating Rules

• Never blend logo churn and revenue churn in one number. They answer different questions and hiding one behind the other is how bad retention gets sold as good.
• NRR above 100 percent does not mean churn is fine. It means expansion is masking churn. Report both numbers side by side.
• Do not compute churn on cohorts younger than one full period. A cohort that signed up last week has no retention data yet.
• Treat voluntary and involuntary churn separately. Failed payments are a billing problem, not a product problem, and dunning fixes them.
• When the data is missing or thin, say so plainly and say which numbers are estimates. A flagged estimate beats a confident guess.
• Keep exit surveys short and in the cancellation flow. Email surveys sent weeks later get low response rates and polite lies.
• Related skills: pricing-basics for the pricing levers that affect churn (packaging, discounts, annual plans); unit-economics for CAC payback and LTV, which churn feeds directly into.