HG Insights|Phoenix

Skill: CSM Health Scoring

One composite health grade per account — Low / Medium / High — every component sourced to a specific HG signal.

Overview

Teach Claude to compose a customer-health composite score the same way every time. Weighted blend of adoption (40%), sponsor coverage (20%), intent posture (20%), and sentiment proxies (20%) — anchored on HG signals the workflow can defensibly cite. Renewal-cycle weight is scored "unknown" unless the workflow takes a CRM-supplied renewal date, because HG MCP does not expose the customer's own product renewal.

Use cases

  • Portfolio triage with grades your team can defend

    Your CSM lead inherits 30 accounts. They run this skill across all of them and get a Low/Medium/High grade per account with the top-2 evidence points each. The 4 Lows get attention week 1; the 18 Highs follow their existing rhythm.

  • Same composite, every workflow

    Account-health scorecard, reference-advocacy finder, and expansion-sequencing workflows all use this skill so the composite math is identical across surfaces — no drift between "healthy enough for a reference" and "healthy enough to expand".

View full skill

CSM Health Scoring

When to use

  • A workflow needs a single Low/Medium/High grade per customer account (composite score 0-100).
  • A workflow is about to invent its own weighting — stop, reference this skill so all surfaces agree.

Tools you'll touch

  • company_install_time_series — adoption signal (the heavy weight).
  • company_fai — sponsor coverage by functional area.
  • company_intent — intent posture (engagement signal proxy).
  • company_firmographic — basic context, never the score itself.
  • company_technographic — corroborating signal for adoption claims.
  • contact_search — verify named sponsors against the {{prior_contacts}} baseline.

Out of scope: company_contracts. That tool returns ICT outsourced contracts (GSI-mediated), NOT the customer's own product contract or renewal date (company-contracts.ts:233-234). Renewal-cycle weight is scored as unknown unless the workflow takes our_contract_renewal_date as a CRM-supplied parameter — see "Composite formula" below.

Composite formula

ComponentWeightSource signalScoring rule
Adoption strength40%company_install_time_series.current_intensity + intensity_momentum40 pts if current_intensity ≥70 AND intensity_momentum ≥0; scale linearly down to 0 pts when current_intensity <30 OR intensity_momentum <-10
Sponsor coverage20%contact_search match-rate against {{prior_contacts}} baseline20 pts if 100% of prior_contacts still surface; 0 pts if 0%
Intent posture20%company_intent filtered to customer's category20 pts if trend ≥+10% on our category; 10 pts if neutral; 0 pts if ≤-30%
Sentiment proxies20%company_firmographic strategic events + company_fai (relevant function intensity stable or growing)20 pts if no strategic-reset events in 90d + relevant FAI is stable; scale down on M&A / RIF / new-CIO signals
Renewal-cycle weight(optional)our_contract_renewal_date (CRM-supplied parameter)If absent: score as unknown and do NOT subtract from the composite. If supplied: apply consumer rule (e.g., -10 if ≤120 days) on top.

Grade mapping

Composite (0-100)Grade
≥70High
40-69Medium
<40Low

Per-component minimum evidence

A component contributes to the composite only if its source signal is fresh (per hg-recent-signals):

  • Adoption: install_time_series last data point ≤90 days old.
  • Sponsor coverage: contact_search is real-time; always fresh.
  • Intent: company_intent last_seen ≤90 days.
  • Sentiment: strategic events ≤90 days, FAI ≤12 months.

If a component is stale, mark it "stale — not scored" and reduce the composite's max possible score. Never invent a missing component.

Why company_contracts is out of scope

The tool returns ICT outsourced contracts (Accenture/IBM/Cognizant-mediated), not the customer's product contract with you. Treating its daysUntilRenewal as "their renewal with us" produces confidently-wrong verdicts. Workflows that need renewal-cycle weight should:

  1. Accept our_contract_renewal_date as a workflow parameter (CRM-supplied).
  2. If absent, score the renewal-cycle weight as "unknown" (omit from the composite, document the gap).
  3. Never compute renewal proximity from company_contracts.

Output convention

Grade + composite + top-2 evidence per component:

Health: Medium (composite 58/100)
- Adoption: 24/40 — current_intensity 62, intensity_momentum -3 [company_install_time_series]
- Sponsor coverage: 14/20 — 2 of 3 prior contacts still match (champion still in seat) [contact_search]
- Intent posture: 10/20 — trend neutral on the [our category] topics [company_intent]
- Sentiment: 10/20 — new CIO appointed 6 months ago, FAI for Engineering down 12% [company_firmographic, company_fai]
- Renewal-cycle: unknown (our_contract_renewal_date not supplied)

Common pitfalls

  1. Treating company_contracts as the customer's product contract. It's GSI-outsourcing data. See "Why company_contracts is out of scope" above.
  2. Inferring sponsor coverage without a prior_contacts baseline. Absence inference is unreliable.
  3. Scoring stale components as if fresh. A 24-month-old FAI reading is not evidence of current sentiment.
  4. Inventing a missing component. If sentiment can't be derived, mark it unscored and reduce the max possible composite.

Reference