churn-detector

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:

{
  "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"