Churn Detector

---
name: churn-detector
description: >
  Weekly churn risk detection across active client accounts. Scans for signals
  like decreased engagement, missed meetings, delayed payments, and competitor
  mentions. Scores risk 1-10 and outputs prioritized alert list.
tags: [account-management, churn, risk-detection, retention]
---

# Churn Detector

Scans all active client accounts for churn risk signals on a weekly cadence. Aggregates behavioral, financial, and communication indicators into a composite risk score (1-10) and generates an actionable alert list with recommended interventions.

## Prerequisites

- `agency.config.json` populated (services, CRM config)
- Active client accounts tracked in CRM with engagement history
- At least 4 weeks of historical data for trend analysis
- Optional: billing/invoice data for payment signal detection

## Capabilities Used

1. `crm-writer` -- read client engagement data from CRM
2. `company-researcher` -- detect competitor or market signals
3. `message-generator` -- draft retention outreach messages

## Phase 0: Intake

Read `agency.config.json`:
- `services[]` -- map active services per client
- `crm.tabs` -- locate client pipeline and engagement data
- `agency.name` -- for output attribution

Accept parameters:
- `scan_scope` -- `all_active` | `specific_client`. Default: `all_active`
- `client_name` -- (required if scope = `specific_client`)
- `lookback_weeks` -- number of weeks to analyze. Default: `4`
- `alert_threshold` -- minimum risk score to flag. Default: `5`
- `include_recommendations` -- boolean. Default: `true`

## Phase 1: Client Inventory

Query CRM for all active client accounts:
- Client name, contract start date, renewal date
- Active services (mapped to `services[]`)
- Primary contact person
- Account owner / relationship manager
- Monthly retainer value
- Last interaction date

Build the scan list. If `scan_scope` = `specific_client`, filter to that account only.

## Phase 2: Signal Detection

For each client, scan across five signal categories:

### 2a: Engagement Signals
- **Meeting frequency change**: Compare meetings held in last 4 weeks vs prior 4 weeks. Flag if >30% decline.
- **Response time degradation**: Average time to reply to emails/messages. Flag if >2x slower than baseline.
- **Meeting no-shows**: Any missed or cancelled meetings in the lookback period.
- **Reduced scope requests**: Fewer tasks, projects, or requests submitted vs baseline.
- **Silence periods**: No communication for 7+ consecutive days (excluding holidays).

Score each signal 0-2:
- 0 = Normal
- 1 = Mild concern
- 2 = Strong signal

### 2b: Financial Signals
- **Late payments**: Invoices paid after due date. Flag days overdue.
- **Payment disputes**: Any invoice questioned or contested.
- **Budget discussions**: Mentions of "budget cuts", "cost reduction", "pausing spend".
- **Scope reductions**: Active services reduced or paused.
- **Contract non-renewal signals**: Approaching renewal with no renewal conversation initiated.

Score each signal 0-2.

### 2c: Satisfaction Signals
- **Negative feedback**: Explicit complaints, dissatisfaction expressed in any channel.
- **Escalation frequency**: Issues escalated beyond normal contact.
- **Deliverable rejection rate**: Percentage of deliverables requiring major revisions.
- **Tone shift**: Communication tone becoming more formal, shorter, or less friendly.
- **Praise absence**: No positive feedback in the lookback period (absence of signal).

Score each signal 0-2.

### 2d: Competitive Signals
Run `company-researcher` (quick depth) to check:
- **Competitor mentions**: Client mentions or follows competing agencies on LinkedIn.
- **Job postings**: Client hiring for roles that overlap with agency services (e.g., "Shopify developer", "CRO specialist").
- **RFP activity**: Signs the client is shopping for alternatives.
- **New vendor announcements**: Client announces partnership with another agency.

Score each signal 0-3 (competitive signals carry higher weight).

### 2e: Usage Signals
- **Dashboard/tool logins**: If client has access to shared dashboards, check login frequency.
- **Report engagement**: Are they opening and reviewing shared reports?
- **Feature adoption**: Are they using all contracted services or ignoring some?
- **Support ticket volume**: Sudden drop may indicate disengagement; sudden spike may indicate frustration.

Score each signal 0-2.

## Phase 3: Risk Scoring

Calculate composite risk score per client:

```
engagement_score = sum(2a signals) / max_possible * 3.0
financial_score = sum(2b signals) / max_possible * 2.5
satisfaction_score = sum(2c signals) / max_possible * 2.0
competitive_score = sum(2d signals) / max_possible * 1.5
usage_score = sum(2e signals) / max_possible * 1.0

raw_total = engagement + financial + satisfaction + competitive + usage
risk_score = round(raw_total, 1)  # Scale 1-10
```

Risk tiers:
- **1-3**: LOW -- healthy account, no action needed
- **4-5**: WATCH -- minor signals, monitor closely
- **6-7**: ELEVATED -- multiple signals, proactive outreach recommended
- **8-9**: HIGH -- significant risk, immediate intervention required
- **10**: CRITICAL -- likely churning, executive escalation needed

## Phase 4: Intervention Recommendations

For each client at or above `alert_threshold`, generate recommendations:

| Risk Tier | Recommended Action |
|-----------|-------------------|
| WATCH (4-5) | Schedule casual check-in call, share a quick win or insight |
| ELEVATED (6-7) | Schedule strategy session, present new value (audit, report), address specific concerns |
| HIGH (8-9) | Executive-level outreach from founder, prepare retention offer, address root causes directly |
| CRITICAL (10) | Immediate call from founder, prepare save plan with concessions if warranted, document lessons |

For each recommendation, draft a brief outreach message using `message-generator`:
- Tone: warm, proactive, value-first (not defensive)
- Content: specific to the detected signals
- CTA: concrete next step (meeting, call, review)

## Phase 5: Alert Report

```
CHURN RISK REPORT -- Week of [Date]
Scanned: N active accounts
---
CRITICAL (1):
  [Client] -- Score: 10/10
  Signals: [top 3 signals]
  Action: [recommendation]

HIGH (2):
  [Client] -- Score: 8.5/10
  Signals: [top 3 signals]
  Action: [recommendation]

ELEVATED (1):
  [Client] -- Score: 6.2/10
  Signals: [top 3 signals]
  Action: [recommendation]

WATCH (3):
  [Client] -- Score: 4.1/10
  [Client] -- Score: 4.0/10
  [Client] -- Score: 4.0/10

HEALTHY (8):
  All clear, no action needed.
---
Total at risk: N accounts
Estimated MRR at risk: INR [amount]
```

## Phase 6: Output

Return structured JSON:

```json
{
  "report_date": "2026-03-07",
  "lookback_weeks": 4,
  "accounts_scanned": 12,
  "alert_threshold": 5,
  "alerts": [
    {
      "client_name": "BrandX",
      "risk_score": 8.5,
      "risk_tier": "HIGH",
      "signals": {
        "engagement": {"score": 2.4, "flags": ["2 missed meetings", "10-day silence period"]},
        "financial": {"score": 2.0, "flags": ["Invoice 15 days overdue"]},
        "satisfaction": {"score": 1.5, "flags": ["Tone shift detected in last 3 emails"]},
        "competitive": {"score": 1.5, "flags": ["Hiring for Shopify developer role"]},
        "usage": {"score": 1.1, "flags": ["Report open rate dropped to 20%"]}
      },
      "top_signals": [
        "2 consecutive meetings cancelled",
        "Invoice 15 days overdue",
        "Hiring for in-house Shopify developer"
      ],
      "recommendation": {
        "action": "Executive outreach from founder",
        "urgency": "This week",
        "message_draft": "Quick note -- noticed we haven't connected in a couple weeks...",
        "next_step": "Schedule 30-min strategy call"
      },
      "mrr_at_risk": 75000,
      "contract_renewal_date": "2026-06-01",
      "days_until_renewal": 86
    }
  ],
  "summary": {
    "critical": 0,
    "high": 1,
    "elevated": 2,
    "watch": 3,
    "healthy": 6,
    "total_mrr_at_risk": 225000
  },
  "generated_at": "2026-03-07T09:00:00Z"
}
```

## Example Usage

**Trigger phrases:**
- "Run churn detection this week"
- "Which clients are at risk of churning?"
- "Check account health across all clients"
- "Is [client] showing churn signals?"
- "Weekly retention scan"
- "Flag at-risk accounts"