Churn Risk Detector

Churn Risk Detector

Deterministic signal extraction + composite scoring; you, the agent, write the root-cause hypotheses, save plays, and talk tracks. The model never invents scores — weights and tiers are fixed in code.

v2.0.0 — depth upgrade. detect_signals.py now carries a comprehensive signal catalog across six lenses — usage decline, login-frequency drop, feature abandonment, support-ticket spike, escalation language, renewal proximity, payment failure, downgrade/seat reduction, NPS/CSAT drop, champion departure, exec/sponsor turnover — each with a fixed threshold + severity feeding the scorecard. This SKILL.md carries the full signal taxonomy, the save-play library, and the output skeleton.

When to use

• "Which customers are at risk of churning?" / "Run the weekly churn risk scan."
• "Who haven't we heard from in a while?" / scheduled weekly customer-health rhythm.

How to run

Step 1 — extract mechanical signals (deterministic, keyless CSV)

python3 ${SKILL_DIR}/scripts/detect_signals.py \
  --customers ${WORKSPACE}/customers.csv \
  --tickets ${WORKSPACE}/tickets.csv \
  --comms ${WORKSPACE}/comms.csv \
  --usage ${WORKSPACE}/usage.csv \
  --billing ${WORKSPACE}/billing.csv \
  --survey ${WORKSPACE}/survey.csv \
  --people ${WORKSPACE}/people.csv \
  --silence-days 30 --renewal-window 60 \
  --output ${WORKSPACE}/signals.json

Detects threshold/keyword signals across six lenses. Only the customer list is required; each missing CSV drops its lens. If the customer list lives in a CRM, pull it first with fetch_customers.py (below), or export from the CRM directly.

Signal catalog (lens · signal · threshold · severity → points)

Severity → composite points are fixed in score_accounts.py: critical 25 · high 15 · medium 8 · low 3 (capped 100). The detector emits these deterministically:

Agent-added (non-mechanical) signals — read the ticket/Slack text yourself and merge in as {name, severity, lens, note} before scoring: negative-sentiment tone shift (vs a numeric NPS drop), champion disengagement (still there but quiet), new-stakeholder asking basic onboarding questions (relationship reset), buying-committee reorg.

Step 2 — score + tier (deterministic)

python3 ${SKILL_DIR}/scripts/score_accounts.py \
  --input ${WORKSPACE}/signals.json \
  --prior ${WORKSPACE}/last_week_scored.json \
  --output ${WORKSPACE}/scored.json

Composite = Σ severity points (critical 25 / high 15 / medium 8 / low 3, capped 100); tiers Red 70-100, Orange 40-69, Yellow 20-39, Green 0-19. Emits per-account breakdown, tier counts, MRR-at-risk by tier, signal distribution, and (with --prior) week-over-week score deltas.

Save-play library (dominant lens → root cause → play)

Pick the play by the account's dominant lens_breakdown lens, then tailor with the specific signals:

Severity-tier response cadence: Red (70-100) = same-week exec-involved save plan; Orange (40-69) = CSM owns a 2-week plan; Yellow (20-39) = watch + one proactive touch; Green = BAU.

Step 3 — write the report (you, the agent)

For each Red/Orange account in scored.json, write a card: signals → root-cause hypothesis → 3-step save play (from the library, tailored) → talk track → escalation trigger + owner + deadline. Add the Yellow watch table, the week-over-week trend (from deltas), the signal distribution, and a "focus this week".

Output skeleton:

# Churn Risk Report — [YYYY-MM-DD]
## Summary
| Tier | Accounts | MRR at risk |
|---|---|---|
| 🔴 Red | N | $X |
| 🟠 Orange | N | $X |
| 🟡 Yellow | N | $X |
Week-over-week: [Red→Green wins · new risks · churned-since-last]

## 🔴 / 🟠 Account Cards  (one per at-risk account)
**[Account] — score X (tier) — $MRR — renews [date]**
- Signals: [list w/ severity + lens]
- Root-cause hypothesis: …
- Save play (3 steps): 1) … 2) … 3) …
- Talk track: "…"
- Owner · deadline · escalation trigger

## 🟡 Watch Table  (account · score · top signal · one action)
## Signal Distribution  (which lenses dominate the book this week)
## Focus This Week  (the 3 accounts/actions with the most MRR leverage)

Optional — CRM customer list

python3 ${SKILL_DIR}/scripts/fetch_customers.py --crm hubspot --output ${WORKSPACE}/customers.csv

Outputs

• risk-report-[YYYY-MM-DD].md — summary table (tier counts + MRR at risk), Red/Orange cards, Yellow watch table, week-over-week trend, signal distribution, "focus this week". Workspace + Agent Teams channel attachment; optional Slack push of the summary.

Credentials / env

• Required: none for the CSV path — detect_signals.py and score_accounts.py are keyless. No LLM key (the agent writes hypotheses + save plays).
• Optional: if a CRM key is set (HUBSPOT_API_KEY / PIPEDRIVE_API_TOKEN / SALESFORCE_*) → fetch_customers.py pulls the customer list live; if not → the keyless CSV/paste path (default). SLACK_BOT_TOKEN — if set → communication-signal source + push; if not → skip. SUPABASE_* — if set → persist run scores for trend history; if not → workspace CSV ledger (default).

Notes & edge cases

• Degrades gracefully: scoring runs on whatever signals exist; minimum viable = customer list + one signal source.
• Keep scoring deterministic (the script's fixed weights); reserve your reasoning for hypotheses, save plays, and sentiment — never hand-edit the composite numbers.
• Persist each run's scored.json so next week's --prior yields Red→Green wins, new risks, and churned-since-last movement.
• Pure analysis — no scraping, no external paid API.