## Reference Skills The following skills are core context for this workflow. Apply their rules to every output you produce. ### Skill: CSM Churn Signal Weighting (csm-churn-signal-weighting) # 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 ([`company-contracts.ts:233-234`](https://github.com/HGData/hip-phoenix/blob/master/webapp/src/server/api/mcp/tools/company-contracts.ts)). 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](https://phoenix.hginsights.com/gtm/skills/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: ` (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](https://phoenix.hginsights.com/gtm/skills/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`](https://github.com/HGData/hip-phoenix/blob/master/webapp/docs/hg-insights-api.md#technographic-endpoints) — `firstVerifiedDate` / `productLocations` semantics - [`hg-insights-api-v2.md#install-time-series`](https://github.com/HGData/hip-phoenix/blob/master/webapp/docs/hg-insights-api-v2.md#install-time-series) — `intensity_momentum` / `data_points` schema - [`hg-insights-api-v2.md#intent-company-intent`](https://github.com/HGData/hip-phoenix/blob/master/webapp/docs/hg-insights-api-v2.md#intent-company-intent) — `/v2/intent/company` `extra: "forbid"` constraint - [`hg-recent-signals`](https://phoenix.hginsights.com/gtm/skills/hg-recent-signals) — canonical recency thresholds - [`hg-citation-discipline`](https://phoenix.hginsights.com/gtm/skills/hg-citation-discipline) — citation format for tool outputs --- ### Skill: HG Recent Signals (hg-recent-signals) # HG Recent Signals ## When to use - A workflow is filtering for "recent" signals and the threshold isn't obvious. - A prompt is about to claim "recently" or "this year" — check the canonical threshold first. - An author is reviewing a workflow output that conflates a 30-month-old install with a 3-month-old one. ## Canonical thresholds | Signal source | "Recent" means… | |------------------------------|-------------------------------------------------------| | `company_technographic` (`first_verified`) | within **24 months** | | `company_technographic` (`last_verified`) | within **12 months** for "fresh", 12-24 for "recent" | | `company_contracts` (new contract) | signed within **6 months** | | `company_intent` (`last_seen`) | within **90 days** (intent decays fast) | | SEC filings | filed within **90 days** | | Press releases / web | published within **90 days** | These are working defaults. A workflow can override with a stricter threshold; do not loosen below these without explicit justification. ## How to read it **Technographic stale-vs-fresh:** - `last_verified` < 12 months ago → **fresh**, lead with the signal. - `last_verified` 12-24 months ago → **recent**, mention the verification date. - `last_verified` > 24 months ago → **stale**, do not lead; pair with a corroborating recent source. **Intent half-life:** intent scores decay quickly. A score-100 from 90+ days ago is a *historical* signal, not an active one. The workflow should re-fetch or downgrade. ## Strategic-signal classification Some events warrant treatment as *strategic* (rewriting the account picture) rather than just "recent". The classification: | Event | Strategic? | Why | |--------------------------------|-----------:|----------------------------------------------------------------------| | M&A — acquired | Yes | New parent + procurement integration window. | | M&A — divested | Yes | Standalone now; original tooling may not survive separation. | | Restructuring (org-wide RIF) | Yes | Budget freeze likely; champion churn likely. | | Leadership change (CIO/CTO) | Yes | Re-evaluation of the entire IT roadmap is normal in the first 6 mo. | | Funding round (>$50M) | Yes | New spend appetite. | | Local team expansion | No | Noise unless the team aligns with the workflow's category. | | Press release on a partnership | Often no | PR ≠ active intent; check intent + technographic. | The classification matters because a strategic signal **resets the recency clock** — a leadership change last month makes 30-month-old technographic effectively "stale" because the new CIO may have already changed the stack. ## Common pitfalls 1. **Calling a 28-month-old install "current".** It might be; verify before leading with it. 2. **Treating press releases as intent.** A partnership announcement is marketing, not a buying signal. 3. **Ignoring leadership change as a recency reset.** Workflows that ground on a 24-month-old technographic at a company with a 4-month-old CIO often produce stale recommendations. ## Reference - [`hg-insights-api.md#recency`](https://github.com/HGData/hip-phoenix/blob/master/webapp/docs/hg-insights-api.md#api-overview) - [`hg-technographic`](https://phoenix.hginsights.com/gtm/skills/hg-technographic) — `first_verified` / `last_verified` semantics --- ### Skill: HG Citation Discipline (hg-citation-discipline) # HG Citation Discipline ## When to use - Authoring or editing a workflow prompt that produces narrative output. - Reviewing a workflow output that quotes HG / SEC / web data — check the citation pattern against this skill. ## The rules ### 1. Cite at source boundaries, not per claim In a paragraph that synthesizes three HG signals, **one citation at the end of the synthesis is enough**, not one citation per signal. Per-claim citation reads like a footnoted research paper; per-source-boundary reads like a brief. **Per-bullet citation** is the exception: when bullets reference different products from different verifications, each bullet carries its own citation. ### 2. One marker per table A markdown table that pulls every cell from `company_technographic` carries **one** citation in the introductory sentence, not one per row. The reader trusts that the table is internally consistent. When a table mixes sources (e.g., HG technographic + SEC headcount), use a footnote-style cite per column. ### 3. Source-priority order When multiple sources can support the same claim: 1. **HG** — primary. Cite as "HG, [month year]" (e.g., "HG, May 2026"). 2. **SEC filings** — for public-company-specific claims (revenue, acquisitions, executive changes). Cite as "SEC 10-K (FY2025)" or similar; the year matters. 3. **Web search** — last resort, only when HG and SEC don't cover the claim. Cite as "web search, [domain.com], [date]". Never cite "general knowledge" or "industry consensus" — that's a tell for fabrication. ### 4. No-fabrication guardrails - **Never invent emails or phone numbers.** `contact_search` returns name + title + location + LinkedIn; if the workflow wants email, call `contact_enrich` explicitly. Otherwise omit. - **Never invent revenue figures.** If `company_firmographic` returns a low-confidence revenue, hedge ("approximately") or omit; do not pick a precise-looking number from web sources without re-citing them. - **Never invent product versions.** `company_technographic` returns a product name, not a version string. "They run Salesforce v59" is a fabrication unless the version came from another tool. - **Never invent deal values.** If `company_contracts` is the source, it's modeled — say so. - **LinkedIn URLs only** for contacts. Don't invent direct-message Twitter handles or personal blogs. ## How this maps to the duplicated caveats The text "CITATION DENSITY" appears nine times in `webapp/src/server/db/blueprint-definitions.ts` — every workflow prompt re-encodes some variation of these rules inline. When a workflow references this skill (composition mechanism in follow-up #B), it should drop those inline lines and add: "Follow the citation discipline in the `hg-citation-discipline` skill." ## Common pitfalls 1. **Trying to be helpful and citing every claim.** It clutters the output and makes the deliverable feel uncertain. Trust the source boundary. 2. **Mixing citation styles within one document.** Pick one (per-paragraph or per-bullet) and stick to it. 3. **Citing HG for things HG doesn't cover.** "HG, May 2026" after a claim about company strategy is wrong if the strategy came from web search; that's an SEC or web cite. ## Reference - [`hg-insights-api.md#citation`](https://github.com/HGData/hip-phoenix/blob/master/webapp/docs/hg-insights-api.md#api-overview) — HG-side guidance on citation language - [`hg-modeled-vs-observed`](https://phoenix.hginsights.com/gtm/skills/hg-modeled-vs-observed) — when to add the "modeled" qualifier # High-Intensity Location Decline Watch ## Parameters - `{{domain}}` *(required)* — Customer company domain. Example: `acme.com` - `{{your_product}}` *(required)* — Your product (the per-site product whose location count is the leading indicator). Example: `Cisco Umbrella` - `{{prior_location_count}}` *(required)* — Baseline location count from a prior brief or CRM. REQUIRED — company_install_time_series.data_points only carries intensity, not locations.. Example: `47` ## Purpose For platforms that deploy site-by-site (industrial, security, point-of-sale), high-intensity locations dropping is the earliest churn indicator. Compare today's `productLocations` for {{your_product}} at {{domain}} against the CRM-supplied {{prior_location_count}} baseline. Surface delta + adoption context. **Important data limit**: `company_install_time_series` `data_points[]` returns `{ date, intensity }` only — no per-month location count. `company_technographic.productLocations` is a current snapshot only. The {{prior_location_count}} parameter is the only baseline. ## Process 1. **Resolve product id** — call `get_vendor_information` for {{your_product}} to get its canonical product/vendor id (exact-product filtering in `company_technographic` requires this; passing a free-text name can miss the product if it's not in the unfiltered top results). Optionally also call `list_product_categories` to confirm the category. 2. **Current snapshot** — `company_technographic` for {{domain}} filtered by the resolved product id. Capture today's `productLocations` and `firstVerifiedDate` (when the product was first detected at the customer). 3. **Adoption context** — `company_install_time_series` for {{domain}} filtered to {{your_product}}, `timeRange: last_12_months`. Capture `intensity_momentum` and `current_intensity`. Location decline + negative intensity momentum is a much louder signal than location decline alone. 4. **Customer context** — `company_firmographic` for {{domain}}: any customer-enrichment context. For explicit event detection (office closures, divestitures, M&A that explain a real-estate footprint contraction), route through `web_search` since `company_firmographic` exposes static fields only, not event streams. 5. **Delta + verdict** — `delta = current productLocations − {{prior_location_count}}`. Verdict: - Delta ≥ 0 → No decline (Watch). - Delta < 0 AND `intensity_momentum` ≥ 0 → Footprint contraction, adoption holding (likely organic office change — Yellow with firmographic context). - Delta < 0 AND `intensity_momentum` < 0 → Coordinated deployment pullback (Red — escalate). ## Output Format - `# 🏢 {{domain}} — Location Decline: ` - `Prior: {{prior_location_count}} sites | Current: sites | Delta: <±N>` - `## Adoption context` — `intensity_momentum` + `current_intensity` + first detected at `firstVerifiedDate` - `## Customer context` — any firmographic event that explains the delta - `## Verdict reasoning` — one paragraph tying the delta + momentum + context to the verdict ## Quality Checklist - {{prior_location_count}} is the baseline — never derive a delta from `data_points` (it carries intensity only) - Verdict cites both location delta AND intensity momentum - Customer context is non-judgmental — flagged separately from the verdict - Cap tool calls at ~6