/digital-marketing-pro:cohort-analysis

/digital-marketing-pro:cohort-analysis

Script location. If your host does not set ${CLAUDE_PLUGIN_ROOT}, the scripts are in this plugin's scripts/ folder, next to skills/. Run them with Python 3.10 or newer: python, or python3 where python is not found (macOS, many Linux systems).

Purpose

Perform customer cohort analysis to understand lifecycle patterns, retention, and value over time. Segment customers into cohorts by acquisition date, channel, behavior, or value tier, then track retention curves, compare cohort performance, and identify which acquisition sources produce the highest-value customers. This analysis reveals whether the business is acquiring better or worse customers over time, which channels drive long-term value versus one-time transactions, and where lifecycle interventions (onboarding improvements, re-engagement campaigns, loyalty programs) would have the greatest impact on retention and revenue.

Input Required

The user must provide (or will be prompted for):

• Cohort type: time-based (customers grouped by acquisition week, month, or quarter — the standard cohort analysis showing retention evolution over time), channel-based (customers grouped by acquisition source — paid search, organic, social, email, referral — revealing which channels produce the most durable customers), behavioral (customers grouped by first action taken — e.g., product category purchased, feature used, content consumed — identifying which entry points lead to highest retention), or revenue-tier (customers grouped by initial purchase value — low, medium, high, enterprise — showing how starting value correlates with lifetime retention and expansion)
• Time period and granularity: The analysis window and cohort size — weekly cohorts for the past 3 months (high resolution, best for fast-cycle businesses), monthly cohorts for the past 12 months (standard for most businesses), or quarterly cohorts for multi-year analysis (best for long-cycle B2B or subscription businesses). Granularity determines both how cohorts are defined and the retention interval measured
• Metrics to track: Which outcomes to measure across cohorts — retention rate (percentage of cohort still active at each interval), revenue (cumulative and per-period revenue per customer), LTV (cumulative lifetime value with projected future value), engagement (login frequency, feature usage, content consumption), or multiple metrics simultaneously for a comprehensive lifecycle view
• Data source: Where to pull customer data — CRM (deal data, customer records, lifecycle stages), analytics (website behavior, conversion events, session data), product analytics (feature usage, activation events, engagement metrics), or a combination of sources merged on customer identifier

Process

1. Load brand context: Read ~/.claude-marketing/brands/_active-brand.json for the active slug, then load ~/.claude-marketing/brands/{slug}/profile.json. Extract business model (SaaS, eCommerce, B2B), typical customer lifecycle length, key retention metrics, and churn definition for the industry. Check for guidelines at ~/.claude-marketing/brands/{slug}/guidelines/_manifest.json. If no brand exists, ask: "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults.
2. Define cohorts based on selected type: Segment the customer base into cohorts. For time-based: group customers by the week, month, or quarter they were first acquired (first purchase, account creation, or first meaningful interaction). For channel-based: group by the acquisition source attributed to their first conversion (UTM source, referral path, or CRM lead source field). For behavioral: group by the first significant action taken (first product category purchased, first feature activated, first content type consumed). For revenue-tier: group by initial transaction value bucketed into tiers (define thresholds based on the business's order value distribution — e.g., bottom 25%, middle 50%, top 25%).
3. Pull customer data from CRM and analytics MCPs: Gather the complete customer dataset — acquisition dates and source from CRM MCP, transaction history with timestamps and values, engagement events (logins, feature usage, email opens, site visits) from analytics MCPs, churn events (cancellation, last activity date, account closure), and any customer attributes needed for cohort segmentation. Merge data from multiple sources on customer identifier, resolving duplicates and filling gaps where possible.
4. Build retention matrix: For each cohort, calculate the retention rate at each subsequent time interval (Week 1, Week 2, Month 1, Month 2, etc. matching the selected granularity). Retention is defined as the percentage of the original cohort that performed a qualifying activity (purchase, login, engagement event — depending on the business model) during that interval. Present as a triangular matrix with cohorts as rows and time intervals as columns, with color-coded cells (green for above-average retention, red for below-average).
5. Calculate LTV by cohort: For each cohort, compute cumulative revenue per customer at each time interval — the average total revenue generated by a customer in that cohort from acquisition through that period. Plot LTV curves showing how value accumulates over time for each cohort. Calculate the LTV:CAC ratio where acquisition cost data is available, identifying which cohorts achieve payback fastest and which generate the highest long-term return.
6. Identify retention patterns: Analyze the retention matrix for structural patterns. When does retention stabilize (the "retention floor" — the period after which churn rate approaches zero)? Which cohorts retain best and what differentiates them from low-retention cohorts (acquisition channel, initial behavior, season of acquisition, promotional vs. organic)? Is there a critical activation window — a specific early-lifecycle period where retention diverges between customers who will retain and those who will churn? Identify the "aha moment" if behavioral data supports it.
7. Calculate cohort health metrics: For each cohort, compute: payback period (months until cumulative revenue exceeds acquisition cost), predicted LTV (extrapolated from the retention curve and revenue trend), churn rate (percentage lost per period, both gross and net), engagement score (composite of activity frequency and depth), and expansion revenue rate (for SaaS — percentage of revenue from upsells and cross-sells within the cohort). Rank cohorts by overall health combining these metrics.
8. Save cohort data for trend tracking: Persist the cohort analysis summary as an insight via python "${CLAUDE_PLUGIN_ROOT}/scripts/campaign-tracker.py" --brand {slug} --action save-insight --data '{"type":"cohort","insight":"retention/LTV/health summary","context":"cohort-analysis {period}"}' for longitudinal comparison — retention floor, LTV curve shape, cohort health scores, and segmentation notes. (Note: churn-predictor.py scores churn risk from behavioral signals; it does NOT store retention matrices or LTV curves — durable cohort history lives in campaign-tracker insights.) Enable month-over-month comparison of whether newer cohorts are retaining better or worse than older ones, whether channel quality is shifting, and whether lifecycle interventions are measurably improving retention curves.

Output

A structured cohort analysis containing:

• Retention matrix: Cohort-by-time-period grid showing retention percentage at each interval — color-coded with above-average cells in green and below-average in red, with cohort size (n) displayed for each row to indicate statistical reliability
• Retention curves visualization data: Plotted retention curves for each cohort overlaid on a single chart — enabling visual comparison of retention trajectory, with the average retention curve highlighted as a baseline reference
• LTV by cohort comparison: Cumulative LTV curves per cohort showing value accumulation over time, with current LTV, projected 12-month LTV, and LTV:CAC ratio where acquisition cost is available
• Best and worst performing cohorts: Ranked cohort list with the top 3 and bottom 3 cohorts by retention and LTV, with hypothesized drivers for each — acquisition channel, seasonal factors, promotional activity, product changes, or onboarding differences that correlate with performance
• Stabilization point analysis: The retention floor for each cohort type — the time interval after which monthly churn drops below a threshold (typically 1-2%) — with implications for payback period planning and customer lifetime estimation
• Cohort trend analysis: Are newer cohorts retaining better than older ones? Month-over-month comparison of same-interval retention rates across cohorts (e.g., Month 3 retention for each successive cohort) showing whether the business is improving or degrading at acquiring durable customers
• Intervention recommendations for underperforming cohorts: Specific, actionable recommendations for improving retention in low-performing segments — targeted re-engagement campaigns, onboarding modifications, product experience improvements, or win-back offers, with projected retention impact based on the gap between underperforming and top-performing cohorts
• Acquisition channel quality ranking by cohort LTV: Channels ranked by the average LTV of customers they acquire — revealing which channels drive long-term value versus which drive one-time or low-retention customers, independent of volume, to inform acquisition budget allocation