CSM Churn Signal Weighting

Compose a defensible Watch / Yellow / Red churn verdict for a customer account from six independent signal classes.

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 and reference this skill.

Tools you'll touch

• get_vendor_information, product_search_and_enrich (action search), get_product_category: resolve your product, competitor products and the category to ids. Cost: free.
• company_install_time_series: monthly detection days and intensity_momentum for your product. Cost: 3 per product row returned, 0 if empty. Always pass product_ids.
• company_technographic: current location_count and competitor adds via product_first_verified_date. Cost: 2 per company.
• list_intent_topics: resolve topic keywords to id. Cost: free.
• company_intent: topic trend on your category and competitors' categories. Cost: 0.1 per call.
• contact_enrich: check that named prior contacts are still at the customer. Cost: 0.2 per email reveal per matched contact; always pass revealPhone:false (a phone reveal adds 2 per matched contact).
• sec_filing_section: 10-K Item 1A and 7A by ticker. Cost: 1 per call, not cached.
• company_ai_maturity (optional): ai_maturity_6m_delta as AI context. Cost: 2 per company, not cached.

One account, one product, two SEC calls: about 8 credits. Company tools cache for 30 days org-wide; a re-run inside the window is not new evidence.

Out of scope: company_contracts. It covers GSI / ICT outsourcing contracts and federal awards only, curated, with no renewal-likelihood or expiry-confidence fields. It is not the customer's contract with you. Renewal proximity comes from CRM as our_contract_renewal_date.

The 6 signal classes

#	Signal	Tool / Field	Strong	Weak
1	Adoption decline	company_install_time_series: intensity_momentum, data_points[].intensity	momentum ≤ -20	momentum -10 to -20
2	Location-count drop	company_technographic: location_count vs a baseline	large drop corroborated by signal 1	any drop vs baseline
3	Competitor add	company_technographic: product_first_verified_date in the lookback	add with location_count ≥ 3	single-location add
4	Intent shift	company_intent: topic trend on resolved topic_ids	decay ≤ -2 or rise ≥ +2	decay ≤ -1 or rise ≥ +1
5	Champion coverage	contact_enrich against prior_contacts	≥ 50% confirmed moved	some moved or unverified
6	Financial stress	sec_filing_section 10-K Item 1A / 7A	going-concern, layoffs ≥ 5%, restructuring	guidance cut, new risk language

1. Adoption decline

Resolve your product to integer product_ids first; guessed ids match nothing and return products: [] at 0 credits.

{ "company_domain": "acme.com", "product_ids": [12345], "time_range": "last_12_months" }

• data_points[].intensity = days detected that month (1 to 31); a mid-series null = no detection (read as 0).
• Drop the trailing null (current month), the month containing product_last_verified_date (from company_technographic) unless that date is at month end, and any later month. That month is partly loaded and looks like a collapse.
• Primary reading: intensity_momentum. ≤ -20 = declining (strong), -10 to -20 = early decline (weak), otherwise stable. ≥ +20 = growing.
• Corroborate with detection days: average the last 3 complete, loaded months. 20 or more = heavy, 5 to 19 = regular, under 5 = sparse. A fall of one band versus the start of the window supports the momentum reading.
• Never use current_intensity for trend: it is an all-time aggregate on another scale.
• is_active:false (not verified in 90 days) counts only if the series declined before detection stopped; otherwise it is inconclusive.

2. Location-count snapshot

location_count is a current count, not a delta, and data_points carry no location count. Flag a drop only against a baseline: a CRM-supplied prior_location_count or a value captured on a prior run, read at the same granularity (passing country_codes switches to per-country rows). A baseline older than 6 months is unreliable.

3. Competitor add

Resolve your category with get_product_category and call company_technographic with category_ids (32-char hex). A row is a competitor-add signal when:

• its vendor_id is not yours,
• product_first_verified_date falls inside the lookback,
• product_last_verified_date is within 90 days (current).

Ignore product_first_verified_date = 2000-01-01: it means "before tracking began". Cite the first-verified date per row.

4. Intent shift

1. Resolve topics with list_intent_topics (one lowercase keyword, for example name:"observability") for your category and each competitor's category.
2. Call company_intent:

{ "company_domain": "acme.com", "fields": ["topics"], "granularity": "global",
  "topic_ids": ["<your topic ids>", "<competitor topic ids>"], "limit": 50 }

3. Read trend per topic row. These thresholds are provisional (the unit is unconfirmed; observed values run about -3 to +7): decay on your topics ≤ -2 strong, ≤ -1 weak; rise on competitor topics ≥ +2 strong, ≥ +1 weak.
4. For a named competitor, add vendor_ids and context_type_names:["Displacement"].
5. Compare the topic_ids you sent with the topics returned. Each missing one is inconclusive, not "no decay": list it as such, and don't summarise the category as "no decay" while any of its topics is missing. data_available:false, or no topics at all at a smaller company, is no coverage. Don't score it.

5. Champion coverage

Only with an explicit prior_contacts baseline. Enrich up to 25 people in one call:

{ "contacts": [ { "firstName": "Jane", "lastName": "Doe", "company_domain": "acme.com" } ], "revealPhone": false }

• Unmatched people are omitted; match rows by name or id, never by position.
• Still in seat: returned organization.domain is the customer. Moved: matched at a different employer. No match: unverified, reported separately.
• Contact data comes from a third-party provider, not HG; cite it as such.
• Without a baseline, skip absence inference. contact_search (2 per call) by title gives function-level context only.

6. Financial stress

sec_filing_section with companyTicker, filingType:"10-K", section:"1A" (Risk Factors) and section:"7A" (Market Risk). It needs a ticker (from the user, CRM or a web search) and covers US domestic issuers only; route foreign filers to sec_full_text_search. "No filing found" doesn't prove the company is private. Skip the signal when there is no ticker.

Optional AI context

For an AI signal, read ai_maturity_6m_delta (score points) from company_ai_maturity as supporting context, not a seventh class. Don't use company_operating_signals stage labels; they are coarse.

Weighting heuristics: Watch / Yellow / Red

Signal Pattern	Verdict
No signal firing, or a single weak signal	Watch (green)
1 strong signal, or 2 to 3 weak signals	Yellow
2+ strong signals, or competitor add ≤ 90 days + intent decay trend ≤ -2 on your category + intensity_momentum ≤ -10	Red

Combo escalators. Any one escalates the verdict by one band:

• A new competitor install with location_count ≥ 3 in the customer's footprint.
• A 10-K Risk Factor disclosing layoffs of 5% or more of the workforce, filed in the last 90 days.
• 50% or more of prior_contacts absent (moved or unverified). Report the split; if most are unverified, note the weaker evidence.

Renewal-cycle awareness. Consumers who supply our_contract_renewal_date from CRM may add their own rule (for example "120 days or less to renewal escalates Yellow to Red"). Renewal proximity is not one of the six signals.

Required content

Layout is up to the formatting skills. Whatever the layout, the answer contains:

• The verdict, stated once, as one of Watch, Yellow or Red.
• For adoption, when the product is installed: intensity_momentum, the 3-month average of monthly detection days with the three months named, and the months left out (current month, partly loaded months) by name.
• For every signal cited: its class (one of the six), the value, the date of that value, and the source tool in brackets (hg-citation-discipline). Example: "intensity_momentum -24, detection days averaged 8 over Jun to Aug 2026 vs 27 at the start of the window [company_install_time_series]".
• Topics requested but not returned, listed as inconclusive.
• Signals not checked, and why (no ticker, no prior_contacts baseline, no coverage).
• Three actions at 30, 60 and 90 days, each tied to a named signal.

Common pitfalls

1. Treating company_contracts as renewal status. It is outsourcing and federal award data with no renewal fields.
2. Reading the partly loaded last month as a collapse. Drop it before computing anything.
3. Comparing current_intensity with monthly detection days. Different scales.
4. Counting a 2000-01-01 first-verified date as a new competitor.
5. Intent without resolved topic_ids, or an absent topic read as "no decay".
6. Enriching contacts with the default revealPhone:true, or inferring champion churn without a baseline.

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-install-time-series
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-technographic
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-intent
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/contact-enrich
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/sec-filing-section
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, csm-health-scoring, hg-recent-signals, hg-intent, hg-sec-research, hg-ai-and-cloud-signals, hg-citation-discipline