Churn Analysis Skill

Produce a structured churn analysis that goes beyond the headline rate — identifying why customers leave, which segments are most at risk, and what interventions will have the highest impact on retention.

Reads from / Writes to the Brain

If a professional-brain (brain/) exists, ground in it instead of re-asking for what you already know:

• Read first: context.md (metric definitions — what "churn" means here), knowledge/, and related segment entities/. Run python3 ../professional-brain/scripts/brain_query.py ./brain "churn" and carry each fact's provenance tag through.
• 📥 Propose to the Brain: after producing, propose recording the headline retention finding to knowledge/ ([data]), any retention decision to decisions/, and at-risk drivers as hypotheses/. Show them, get a yes, then write with ../professional-brain/scripts/brain_write.py … --commit (append-only, dry-run by default).

Required Inputs

Ask for these if not already provided:

• Time period being analysed (e.g. Q1, last 12 months)
• Total customers at start of period and customers churned
• ARR or revenue lost to churn
• Churn reasons data — exit survey results, CSM notes, support data, or sales loss reasons
• Customer segments — by tier, industry, cohort, or product line
• Current retention rate if known
• Any recent changes — pricing, product, support model — that may have affected churn

Churn Categories

Always classify churn before analysing it:

The interventions for each category are different. Conflating them leads to wrong conclusions.

Output Format

---

Churn Analysis: [Product / Segment / Company]

Period: [Start date] — [End date] Prepared by: [Name] | Date: [Date]

---

Headline Numbers

Benchmark context:

• Customer churn rate: [X]% vs. industry benchmark [Y]% — [above / below / in line]
• NRR: [X]% — [What this means: above 100% = expansion offsets churn; below 100% = shrinking base]

---

Churn Breakdown by Category

Avoidable churn as % of total churn: [X]% — this is the number we can actually influence.

---

Churn Reasons — Avoidable Churn Only

Rank by frequency. Include ARR weight where data allows.

Theme synthesis: [2–3 sentences grouping the top reasons into 2–3 themes. E.g. "The top three reasons cluster around two themes: product gaps in [area] (affecting X% of avoidable churn) and onboarding failures where customers never achieved value (Y%)."]

---

Churn by Segment

Identify which segments over- or under-index for churn.

By Tier

By Cohort (Acquisition Year)

By Industry / Use Case (if data available)

Key pattern: [Which segment has the highest churn rate and what likely explains it]

---

Timing Analysis

• Average contract length before churn: [X months]
• Highest-risk moment: [e.g. "Month 3 — when trial value has worn off but full adoption hasn't happened"]
• Churn timing distribution:

---

Early Warning Signals

Based on the churned accounts, identify the signals that preceded churn (and could have triggered earlier intervention):

---

Intervention Recommendations

Ranked by estimated impact × feasibility.

Priority call: [Which one intervention, if implemented this quarter, would have the biggest impact and why]

---

What We Don't Know (Data Gaps)

• [Data gap 1 — e.g. "Exit survey response rate is only 30% — the reasons data may not be representative"]
• [Data gap 2 — e.g. "No product usage data for SMB tier — can't confirm usage signal correlation"]
• [Data gap 3]

---

Anti-Patterns

• Do not mix avoidable and unavoidable churn in intervention plans — recommending product fixes for customers who churned due to company shutdown wastes resources
• Do not calculate churn rate using end-of-period customer count as the denominator — this understates churn; always divide churned customers by the starting cohort
• Do not rely solely on exit survey data for churn reasons — response rates are typically low and self-selection biases the sample toward customers who are engaged enough to complete a survey
• Do not recommend interventions without linking them to a specific churn reason — interventions disconnected from root causes will not move retention
• Do not report only gross revenue churn — without net revenue retention (NRR), a healthy-looking retention number can hide a shrinking revenue base

Deeper Materials

This skill ships with support files — use them when they are available:

• references/avoidability-calls.md — Avoidable or Not? The Judgment Calls in Churn Classification. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
• templates/churn-report.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

Quality Checks

• Churn rate is correctly calculated (churned ÷ starting cohort, not end-of-period total)
• Avoidable and unavoidable churn are separated — interventions target avoidable churn only
• Churn reasons are customer-reported, not internally assumed
• Segment analysis identifies which segments over-index — not just averages
• Early warning signals are specific and detectable, not generic ("low engagement")
• Interventions link directly to the top churn reasons — no recommendations without a root cause match

---

Supporting file: references/avoidability-calls.md

Avoidable or Not? The Judgment Calls in Churn Classification

The whole value of churn analysis lives in one column: avoidable vs unavoidable. Get it wrong in either direction and the interventions are wrong — over-classify as unavoidable and you absolve the product; over-classify as avoidable and you chase ghosts. These are the calls.

The honest taxonomy

The three-signal verification

Never classify on the exit survey alone. Triangulate: stated reason × usage trajectory (when did engagement actually die — usually 60-90 days before the cancel) × support/commercial history. When the signals disagree, the usage trajectory is the honest one.

Bad-fit churn is an acquisition finding

A cohort that churns in month 2 having never activated didn't fail at retention — they were sold something they didn't need. Route it to marketing/sales targeting with the segment named, or the analysis punishes the wrong team.

The intervention mapping rule

Every avoidable cluster must map to an intervention at the moment the signal appeared, not at the cancellation: the day usage dipped, the day the champion left, the day the third P1 hit. Interventions at the exit interview are condolence cards.

---

Supporting file: references/worked-example.md

Worked Example — Churn Analysis

The brief

Harborline sells warehouse-operations SaaS to 3PLs and e-commerce brands. FY2025: started the year with 480 customers and $9.6M ARR; 42 accounts churned, taking $684K ARR with them; expansions added $912K over the same period. Exit surveys came back from 16 of the 42 (38%), CSM notes exist for the rest. The CRO wants "the real churn story, not the dashboard number" before renewal-season planning.

The output

---

Churn Analysis: Harborline — Full Customer Base

Period: 1 Jan 2025 — 31 Dec 2025 Prepared by: M. Osei, RevOps | Date: 12 Jan 2026

---

Headline Numbers

Benchmark context:

• Customer churn rate: 8.8% vs. ~10% typical for SMB-heavy B2B SaaS — slightly better than benchmark, but the mix hides a problem (see segments).
• NRR: 102.4% — expansion is just offsetting churn. Above water, but a $228K net gain on a $9.6M base is treading, not compounding.

---

Churn Breakdown by Category

Avoidable churn as % of total churn: 57% — this is the number we can actually influence. The 11 unavoidable losses (two acquisitions, six budget shutdowns of the warehouse function, three company closures) do not belong in the intervention plan.

---

Churn Reasons — Avoidable Churn Only

Theme synthesis: Avoidable churn clusters into two themes: a product ceiling (multi-warehouse, 37% of avoidable ARR) that growing customers hit at exactly the moment they become most valuable, and value-realisation failures (onboarding + champion loss, 50% combined) where the product was never the problem — the account just never got, or lost, its internal reason to exist.

---

Churn by Segment

By Tier

By Cohort (Acquisition Year)

Key pattern: The 2024 SMB cohort is the epicentre: acquired with a low-touch motion, onboarded without a check-in, and churning inside year one. The headline 8.8% is calm; this cell is not.

---

Timing Analysis

• Average contract length before churn: 14 months
• Highest-risk moment: Months 3–6 — trial enthusiasm has faded, but live operations (the actual value moment) haven't started for stalled accounts
• Churn timing distribution:

---

Early Warning Signals

---

Intervention Recommendations

Priority call: The champion-change playbook — lowest effort, immediately deployable, and it protects the existing base this quarter while the product ceiling fix (the bigger prize) takes two quarters to ship.

What We Don't Know (Data Gaps)

• Exit survey response rate is 38% — reasons for 26 of 42 accounts rest on CSM notes, which skew toward relationship explanations over product ones
• No usage telemetry for the 2023-and-earlier cohort (instrumented in Jan 2024) — early-warning thresholds are calibrated on newer accounts only
• Involuntary churn (7 accounts) has no dunning data — we can't yet say how many were recoverable payment failures

---

Why it's shaped this way

• The denominator is the starting cohort (480), not year-end count — the skill's anti-pattern list bans the flattering version of the math.
• NRR sits beside gross churn in the headline table because 7.1% gross alone would look healthy while the base quietly treads water; 102.4% tells the truer story.
• Interventions target only the avoidable 57% — the acquisitions and shutdowns are reported, then excluded, exactly as the category table demands.
• Every intervention row names the reason it addresses — the skill bans recommendations without a root-cause match, so "improve product marketing"-style orphans don't appear.
• The segment section leads with the over-indexing cell (2024 SMB cohort), not tier averages — averages are what the anti-patterns call out as hiding the pattern.
• The priority call picks the low-effort playbook over the big product fix — a realistic tension: the largest ARR driver is not the first move, and the report says why.
• Data gaps admit the 38% survey response rate up front, per the anti-pattern about exit-survey self-selection — the reasons table is presented as evidence, not gospel.

---

Supporting file: templates/churn-report.md

Churn report: [period] — [segment scope]

Headline

Gross churn: [n logos / $x MRR] ([x]%) · Net revenue retention: [x]% · vs last period: [Δ]

Classification (three-signal verified — references/avoidability-calls.md)

The avoidability split

Avoidable: [x]% of churned MRR → intervention territory Bad-fit at acquisition: [x]% → routed to [marketing/sales] with segment: […] Truly unavoidable: [x]% → priced into the model, not grieved

Timing analysis

Engagement death preceded cancellation by median [n] days. The missed window: [what signal, when].

Early-warning signals (from this cohort's trajectories)

Interventions (ranked by saved-MRR estimate ÷ effort)

What we'll know next quarter that we don't now

[the instrumentation/interviews committed]

---

Supporting file: skills/professional-brain/SKILL.md

Professional Brain Skill

🚀 New to this? Start with the 5-minute Quickstart (../../BRAIN_QUICKSTART.md) — a folder + one file, with a worked example. This file is the full reference.

Most skills start cold — you paste the same context every time, and decisions made six weeks ago lose the why. This skill gives the library a memory: a plain-markdown brain/ folder on disk that skills read before they answer and write to after. No vector DB, no cloud — just grep-able files you (and Claude) can audit and edit.

This is the state layer of an AI teammate. Pair it with the action layer (skills that file tickets / open PRs) and you get a loop: recall → do the work → record the decision → review.

What This Skill Produces

• A scaffolded brain/ folder with a fixed schema (see below).
• Provenance-tagged knowledge — every claim says where it came from and how strong it is.
• Four operations you can invoke: init, ingest, recall, review.
• A standing contract other skills follow: read the relevant brain files first; write durable outcomes (decisions, new facts, stakeholder asks) back.

Required Inputs

Ask for these only if they aren't already on disk or in the request:

• Which operation — init, ingest, recall, or review (default: infer from the ask).
• For ingest: the artifact (a pasted note, a file path, a transcript) and what it's about.
• For recall: the topic or question to answer from memory.
• The brain location — default ./brain/ at the project root.

The Brain Schema

brain/
  context.md      # who/what: product, ICP, metrics definitions, voice (supersedes pm-context.md)
  knowledge/      # durable facts — strategy.md, market.md, users.md, org.md
  decisions/      # one file per decision: what, why, alternatives rejected, reopen-when
  hypotheses/     # assumptions: statement, evidence, status (open/validated/invalidated)
  stakeholders/   # one file per person: asks, concerns, comms history
  entities/       # typed objects: features, accounts, experiments — the artifact graph
  source/         # immutable originals (audit trail) — never edited after capture

It is Obsidian-vault compatible: open brain/ as a vault and the links become a graph.

Provenance Tags (the trust mechanism)

Every fact carries a tag in square brackets so its strength is explicit. Skills must keep the tag when they reuse a fact, and downgrade confidence for weak tags.

Example: Mobile drives 65% of DAU [data]. Enterprise wants SSO before renewing [verbal].

Operations

init — Create the folder schema. Migrate an existing pm-context.md into context.md. Offer to ingest any artifacts the user already has (Notion export, Jira CSV, notes).

ingest <thing> — Store the original verbatim in source/, then synthesise it into the right durable file(s) (knowledge/, decisions/, hypotheses/, stakeholders/), tagging each extracted claim with its provenance. Never discard the source.

recall <query> — Answer from memory. Use the helper script to find matching facts across the brain, then synthesise an answer that cites each fact's file and tag. If memory is thin, say so rather than inventing.

record — The write-back half of the loop (Phase 1). After a skill produces an artifact (or on demand), extract the durable outcomes worth remembering — decisions made, new facts learned, assumptions surfaced, stakeholder asks — and propose them as a numbered list, each with its target section and provenance tag. This is the action surface, so it is approval-gated and dry-run by default:

1. Propose — show the records you'd write (section · tag · text). Preview with brain_write.py … (no --commit), which prints exactly what would be appended.
2. Approve — the user confirms, edits, or drops items. Never write without a yes.
3. Append — write the approved records with --commit. Append-only: decisions become a new numbered file; everything else appends to its named file. Nothing is overwritten.

Downgrade weak evidence honestly — a conclusion from one call is [interview], a gut call is [hunch]; don't launder it into [data].

review — Weekly sweep. Flag: stale hypotheses (open too long with no new evidence), decisions whose reopen-when condition now holds, contradictions between files, and facts that are only [hunch]/[verbal] but are being treated as settled. Draft the updates; don't apply silently.

Programmatic Helper

scripts/brain_query.py (stdlib only) does deterministic recall — it greps the brain for a query and returns matches with their file and detected provenance tag, so retrieval is transparent (no embeddings, no guessing).

# Find what the brain knows about "activation", newest-first, as text
python3 scripts/brain_query.py ./brain "activation"

# JSON for chaining into another step
python3 scripts/brain_query.py ./brain "enterprise SSO" --json

Use its output as the grounded evidence set, then synthesise the answer on top — never answer a recall from outside the brain without saying so.

scripts/brain_write.py is the write-back counterpart — it appends a provenance-tagged record (append-only, never overwrites) and is dry-run by default so you can preview before committing:

# Preview what would be written (changes nothing):
python3 scripts/brain_write.py ./brain decisions "Prioritise mobile" --tag data --body "68% of churn is mobile" --source "Q3 analytics"

# Write it after approval:
python3 scripts/brain_write.py ./brain decisions "Prioritise mobile" --tag data --body "…" --source "Q3 analytics" --commit

The contract for other skills

A brain-aware skill adds a short "Reads from / Writes to the Brain" section:

• Reads: before producing, pull the relevant files (e.g. prd-template reads context.md, knowledge/strategy.md, and any related hypotheses/ + entities/).
• Writes: after producing, append durable outcomes (e.g. meeting-notes writes each decision to decisions/, new asks to the relevant stakeholders/ file), each provenance-tagged.

Output Format

For ingest, confirm what was captured:

Ingested: [artifact]

• Source saved: source/[file]
• Knowledge updated: knowledge/[file] — [facts added, each tagged]
• Decisions logged: decisions/[id] — [if any]
• Hypotheses touched: [statement → status]
• Open follow-ups: [anything needing a human]

For recall, answer then show your grounding:

Recall: [query]

[Synthesised answer.]

Grounded in:

• decisions/0003-...md — "..." [data]
• stakeholders/sarah.md — "..." [verbal]

Quality Checks

• Every extracted claim carries a provenance tag
• The verbatim original is saved in source/ before synthesis
• Recall answers cite the file + tag for each fact, and flag thin memory instead of inventing
• Decisions record the rejected alternatives and a reopen-when condition
• [hunch]/[verbal] facts are never presented with the confidence of [data]/[interview]

Anti-Patterns

• Do not paraphrase a source into the durable layer without keeping the original in source/ — the audit trail is the point
• Do not drop provenance tags when reusing a fact — an untagged claim is an unfalsifiable one
• Do not answer a recall from general knowledge and present it as something the brain "knows" — say when memory is empty
• Do not overwrite a decision when it changes — append a new dated entry so the history survives
• Do not build a vector database or hide memory behind embeddings — the brain stays plain, grep-able markdown a human can read and correct