Risk Signal Detector

Monitors risk indicators across the portfolio and generates prioritised alerts. Part of the Book Intelligence detection layer -- consumes data from the Health Score Engine and Usage Pattern Monitor, produces a ranked risk queue for human triage.

This is a detection and prioritisation skill. It identifies signals, scores severity, and ranks accounts for human attention. It never initiates customer contact, triggers save plays, or makes intervention decisions. Those are human territory.

When to Run

• Event-based triggers: Near-real-time monitoring via webhooks or event streams for champion departure, P1 support tickets, declined meetings, competitive mentions
• Metric-based triggers: Scheduled cadence aligned with Health Score Engine (daily for high-touch, weekly for scaled)
• On-demand: When a human requests the current risk queue or risk assessment for a specific account

Signal Registry

The risk signal registry defines every signal the detector monitors. Each signal has a type, a severity weight, a detection method, and evidence requirements.

Metric-Based Signals

Event-Based Signals

See references/signal-registry.md for the full registry with detection logic and tuning guidance.

Core Execution Logic

Step 1: Evaluate Incoming Signals

For each trigger (event or scheduled metric check):

1. Match the signal against the signal registry
2. Validate evidence requirements are met (do not alert on incomplete data)
3. Score severity using the registry weight

Step 2: Check for Signal Clustering

Multiple signals on the same account within a 14-day window amplify severity:

• 2 signals: severity of the highest signal +1
• 3+ signals: severity of the highest signal +2
• Cap at 5

Clustering is the strongest predictor of near-term churn. A single declining metric is a watch item. Three signals converging on one account is urgent.

Step 3: Apply Temporal Weighting

Signals carry more urgency when renewal is near:

• >180 days to renewal: no adjustment
• 90-180 days: severity +0.5
• 30-90 days: severity +1
• <30 days: severity +1.5 (round up)

Step 4: Rank the Risk Queue

Produce a ranked list of all accounts with active risk signals, ordered by:

1. Adjusted severity score (highest first)
2. Days to renewal (soonest first, as tiebreaker)
3. ARR (highest first, as secondary tiebreaker)

Step 5: Generate Alert Briefs

For each account in the risk queue, produce an alert brief:

{
  "account_id": "string",
  "account_name": "string",
  "risk_score": 4.5,
  "arr": 85000,
  "days_to_renewal": 67,
  "health_score": 58,
  "active_signals": [
    {
      "signal": "Usage gradual decline",
      "severity": 3,
      "evidence": "Session depth declining 4 consecutive weeks, now 22% below 90-day baseline",
      "first_detected": "2026-02-15",
      "source": "bi-usage-monitor"
    },
    {
      "signal": "Champion departure",
      "severity": 5,
      "evidence": "Jane Smith (VP Product) left the company per LinkedIn update 2026-02-28",
      "first_detected": "2026-03-01",
      "source": "crm-contact-change"
    }
  ],
  "cluster_amplification": true,
  "temporal_adjustment": 1.0,
  "suggested_investigation": "Champion departure coincides with usage decline. New sponsor unknown. Priority: identify new stakeholder and assess relationship continuity before renewal window.",
  "handoff_urgency": "immediate"
}

Step 6: Suppress Duplicates

Do not re-alert on the same signal unless:

• Severity escalates (e.g., gradual decline progresses to a 4th consecutive period)
• A new correlated signal appears on the same account
• 14 days have passed since the last alert with no human acknowledgement

Step 7: Generate Daily Digest

Produce a daily summary for the CSM:

• New alerts since last digest
• Escalated alerts (existing signals that worsened)
• Resolved alerts (signal conditions no longer met)
• Portfolio risk trend (total risk signals this week vs. prior week)

Handoff to Human

Every risk alert surfaces to human for triage. The agent does not act on risk.

The human decides: investigate, escalate, trigger a save play, monitor, or dismiss. See references/human-decision-guide.md.

Confidence and Limitations

• High confidence for signal detection (binary: the signal is present or it is not)
• Medium confidence for prioritisation (severity weights are defaults -- they need tuning per portfolio based on historical churn correlation)
• Low confidence for causal inference. The agent presents signals and correlations. It does not explain why the customer is at risk. That is human interpretation
• Cannot detect risks that exist only in relationship context (private dissatisfaction, internal political shifts, unvoiced budget concerns)
• Signal clustering amplification assumes signals are independent. If two signals share a root cause (e.g., a product outage causes both usage decline and support spike), the amplification may overstate severity

Dependencies

Required:

• bi-health-score (composite and component scores, trends)
• bi-usage-monitor (pattern alerts)
• CRM API (contact changes, activity data, opportunity stages)
• Support platform API (ticket data, escalations)
• Calendar integration (meeting declines)

Optional but high-value:

• Email integration (no-reply streak detection)
• LinkedIn integration or stakeholder change detection service (champion departure)
• Call transcript integration (competitor mentions)
• Billing system (payment overdue signals)

Downstream consumers:

• bi-account-brief (active risk signals for account context)
• bi-segment-trends (aggregate risk by segment)
• Human triage queue

References

• references/signal-registry.md -- Full signal definitions, detection logic, and tuning guidance
• references/severity-calibration.md -- How to adjust severity weights based on historical churn data
• references/human-decision-guide.md -- How CSMs should triage and respond to risk alerts