CSM Churn Signal Weighting

When to use

• A workflow is composing a Watch/Yellow/Red verdict on a customer's churn risk.
• A workflow is asked "is this account healthy?" and needs a defensible heuristic.
• An author is about to inline weighting rules into a churn-adjacent workflow — stop, reference this skill.

Tools you'll touch

• company_install_time_series — adoption intensity over a closed enum window (timeRange: last_6_months / last_12_months / last_24_months / last_36_months).
• company_technographic — current-snapshot tech footprint with firstVerifiedDate and productLocations per row (camelCase MCP surface).
• company_intent — top-N topics per company (default limit: 50, max 200) with trend. Endpoint is extra: "forbid" — filter post-fetch.
• company_operating_signals — 6-month deltas (cloud_depth_6m_delta, ai_maturity_6m_delta, etc.).
• contact_search — title / seniority / location filter for the customer's buying-committee function (NOT name-based — that's contact_enrich).
• contact_enrich — verify a NAMED individual (firstName + lastName) is still at the customer, for explicit {{prior_contacts}} baselines.
• sec_filing_section — 10-K Item 1A/7A for financial-stress signals (public companies only).
• list_intent_topics / intent_category — resolve category → topic IDs for the post-fetch filter.

Out of scope: company_contracts. That tool returns ICT outsourced contracts (GSI-mediated — Accenture, IBM, Cognizant), NOT the customer's own product contract or renewal date (the tool reference). Any workflow that needs renewal proximity must take our_contract_renewal_date as a CRM-supplied parameter.

The 6 signal classes

#	Signal	Tool / field	Recency
1	Adoption intensity decline	company_install_time_series.intensity_momentum and current_intensity vs lookback-start	window-driven
2	Location-count snapshot	company_technographic.productLocations (current only — NOT a delta)	snapshot
3	Competitor detection	company_technographic.firstVerifiedDate for net-new products in customer's category	within lookback
4	Intent shift	company_intent.topics[].trend (post-fetch filter by topic_id)	over lookback
5	Champion coverage	contact_enrich per-name against {{prior_contacts}} baseline (NOT contact_search — that doesn't filter by name)	current
6	Financial stress	sec_filing_section 10-K Item 1A/7A	last 90d

1. Adoption intensity decline

intensity_momentum is negative when adoption is declining. Treat as a decline signal when:

• intensity_momentum < -10 (strong negative)
• AND/OR current_intensity is down ≥20% vs the first data_points entry in the lookback.

data_points[] returns { date, intensity } per month — no location count is included. Do not claim a location-count time-series from this tool.

2. Location-count snapshot

productLocations is a current count, NOT a delta. The skill flags a location decline only when the workflow has a baseline:

• A prior_location_count parameter (CRM-supplied), OR
• A captured value from a prior run.

Workflows that try to derive a 6-month location delta from install_time_series.data_points are wrong — that field carries intensity, not location count.

3. Competitor detection

Compute the customer's category from their own product ({{your_product}}), then filter company_technographic rows where firstVerifiedDate falls inside the lookback AND the row's category overlaps. Each surfaced row is a competitor-add signal. Cite firstVerifiedDate per row.

4. Intent shift (decay or rise)

company_intent returns top-N topics by score per company (default 50, max 200). Workflow shape:

1. Resolve the customer's category → canonical topic_ids via list_intent_topics.
2. Call company_intent with limit: 200 for the domain.
3. Post-fetch filter topics[] for the resolved topic_ids.
4. Check trend:
   • trend ≤ -30% on a topic matching the customer's category → decay signal.
   • trend ≥ +30% on a topic matching a competitor's category → rise signal.
5. If the resolved topic_id is absent from the returned topics[], treat as inconclusive (NOT "no decay"). Fall back to intent_category with the specific topic_name (returns company-list for the topic; filter the result to {{domain}}).

5. Champion coverage

For each name in {{prior_contacts}}, call contact_enrich with parsed firstName + lastName + companyDomain. contact_search does NOT accept name filters — only personTitles, personSeniorities, personLocations (verified in contact-search.ts:46-104). If {{prior_contacts}} is empty, skip absence inference — contact_search for the relevant title/seniority gives function-level context only, not named-presence verification.

6. Financial stress

sec_filing_section 10-K Item 1A (Risk Factors) and Item 7A (Quantitative Disclosures). Layoffs ≥5% workforce, guidance misses, going-concern flags, restructuring — all signal stress. Public companies only.

Recency / decay windows

Defer to the HG Recent Signals skill for the canonical thresholds. CSM-specific additions:

• 30/60/90-day adoption deltas — install_time_series covers this via the timeRange enum (last_6_months is the shortest available window; for finer-grained periods, work from the data_points series directly).
• Location-count baselines decay quickly — a prior_location_count older than 6 months is unreliable.

Weighting heuristics — Watch / Yellow / Red

Composing the verdict combines signal strength + signal count. The skill is the source of truth for the rubric.

Signal pattern	Verdict
0-1 signals firing, or only weak signals (intensity_momentum between -1 and -10)	Watch (green)
1 strong signal OR 2-3 weak signals	Yellow
2+ strong signals OR (competitor add ≤90d + intent decay ≥30% on our category + adoption intensity_momentum < -10)	Red

Combo escalators — any one of these escalates by one band:

• New competitor with productLocations ≥3 in the customer's geo footprint (broad competitor install).
• 10-K Risk Factor disclosing layoffs ≥5% workforce in the last 90 days.
• prior_contacts ≥50% absent from per-name contact_enrich results (champion erosion).

Renewal-cycle awareness — consumers who supply our_contract_renewal_date (CRM) may apply their own escalation rule on top (e.g., "≤120 days to renewal escalates Yellow → Red"). The skill does not require this parameter; renewal proximity is NOT a churn-prediction signal in the core 6.

Output convention

Verdict line: Verdict: <Watch|Yellow|Red> (color-coded).

Top-3 signals: 3 bullets, each with:

• Signal name (one of the 6 classes).
• Evidence (specific number, e.g., "intensity_momentum: -18; current_intensity dropped 35% over last_6_months").
• Source citation per hg-citation-discipline ([company_install_time_series]).

Recommended actions: 3 actions sequenced 30 / 60 / 90 days, each tied to a named signal.

Common pitfalls

1. Treating company_contracts as renewal-status. It's GSI-outsourcing data. See "Out of scope" above.
2. Inferring location decline from install_time_series.data_points. That field carries intensity only. Need a baseline parameter.
3. Treating "topic absent from company_intent response" as "no intent decay". It's inconclusive — fall back to intent_category.
4. Inferring champion churn without a prior_contacts baseline. Absence inference is unreliable.

Reference

• hg-insights-api.md#technographic-endpoints — firstVerifiedDate / productLocations semantics
• hg-insights-api-v2.md#install-time-series — intensity_momentum / data_points schema
• hg-insights-api-v2.md#intent-company-intent — /v2/intent/company extra: "forbid" constraint
• hg-recent-signals — canonical recency thresholds
• hg-citation-discipline — citation format for tool outputs