Churn Survey Analyzer

What this skill does

Reads a churn (cancellation/exit) survey CSV and produces a prioritized list of reasons. Each reason includes count, share, verbatim quotes, and 1-3 mitigation ideas tailored to that reason class.

Inputs

• survey_path: CSV with at least reason_category, free_text, plan_at_cancel, tenure_days, mrr.
• Optional mitigation_library: YAML mapping reason classes to candidate mitigations; otherwise use a built-in default.
• Optional out_path: defaults to churn-analysis.md.

Steps

1. Read the CSV. Validate required columns; reject rows with empty free_text (categorical-only rows still count for category share).
2. Normalize reason_category: lowercase, replace synonyms (too expensive -> price).
3. For each category, count rows and sum mrr (the dollar amount of impact).
4. Cluster free_text within each category: TF-IDF + k-means with k auto-tuned. Emergent sub-themes get their own row in the output.
5. Compute per-category: count, %share of churned, sum_mrr, %share of mrr. Use mrr-weighted ranking; small accounts shouldn't dominate over enterprise loss.
6. For each top category (by mrr-weighted rank), look up mitigations in mitigation_library:
   • price -> annual discount, value-tier framing, expansion path.
   • missing-feature -> roadmap update, beta access, partner integration.
   • bugs/quality -> support outreach, P0 fix list.
   • team-change -> hard to mitigate; offer pause/free seat.
   • competitor-switch -> win-back offer, comparison battlecard.
7. Pick 2-3 verbatim quotes per category that best illustrate the theme.
8. Render a markdown report: ranked list of reasons, quotes, mitigation ideas, and a final "Quick wins" section pulling top mitigations.
9. Save to out_path.

Output

churn-analysis.md with: summary header (total churned accounts, total MRR lost, NPS-style breakdown), per-category sections, and a "Mitigations to try first" section. Plus churn-categories.csv for tracking.

Verification

Recompute total MRR lost and confirm it equals sum(mrr) from the source CSV. Sample three quoted responses and confirm the source rows match exactly (no paraphrasing). For each suggested mitigation, confirm it's actually implementable (e.g., "annual discount" requires billing system support — mark as "needs approval" if not). Re-run after a quarter; mitigation success should show up as a category-share decrease.

Edge cases

• Surveys where free_text is mostly empty: rely on reason_category totals only and skip clustering.
• Categories like "other" or "no specific reason": surface separately; don't try to cluster catch-all bins.
• Time-windowed analysis (last 30 days vs trailing 12 months): allow filtering by a cancel_date column if present.
• Sensitive responses (mentions of personal hardship): redact identifying details from quotes before publishing.