score-leads

What this skill does

# Score Leads

Tier leads as Hot / Warm / Cold with a response-time SLA tuned to the use case. Calls `get_gtm_context(detailed: true)` unconditionally, resolves leads by email (deterministic) or name+company (surface ambiguity), scores on four axes, and presents a **scannable** per-lead output with a specific "why now" reasoning snippet so the rep can trust the tier.

## The bar

1. **Tier and SLA are the first thing the rep sees** — not buried under TL;DR or component breakdown.
2. **Resolution accuracy 100%** — every input bucketed; email typos fail loudly, never silent fallback to name search.
3. **Every Hot lead carries verified contact data** — phone + accuracy score visible. Bad data on a Hot lead = dial-the-wrong-number failure.
4. **Every tier comes with a concrete next action** — "Direct dial 555-1234. Lead with [signal]." Not "engage promptly."
5. **Every lead carries a "why now" reasoning snippet** — citing the specific axis driver (person seat × source × fresh trigger / intent / prior engagement). Never the composite restated; never generic ("strong fit"). Same trust discipline as `score-accounts`.
6. **Output scannable in <30 seconds per row.** Component breakdown below the fold.

## Scope

Scores **individual leads**, not accounts. Use `score-accounts` for company-level prioritization. For Hot leads, chain to `personalize-email`.

## Input

- **Leads (required)** — list of ZI person IDs / emails / name+company rows / mixed CSV.
- **Source (recommended)** — `demo_request`, `pricing_inquiry`, `free_trial`, `product_signup`, `content_download_high_intent`, `content_download_low_intent`, `webinar_attended`, `webinar_registered`, `newsletter_subscribe`, `cold_inbound`, `unknown`. If missing, ask once then default to `unknown` (source = 50, flagged).
- **Use case (default `inbound_routing`)** — `inbound_routing`, `event_followup`, `pql_triage`, `content_follow_up`. Drives SLA tuning.
- **Weight overrides (optional)** — `{person, account, source, trigger}` summing to 100.
- **Tier thresholds (optional)** — `{Hot, Warm}`. Cold is the remainder.

## Four-axis framework

| Axis | Question | Source | Default weight |
|---|---|---|---|
| **Person fit** | Is this individual a buyer persona? | `enrich_contacts` | **35%** |
| **Account fit** | Does their employer match ICP? | `enrich_companies` vs `get_gtm_context.icp` | **25%** |
| **Source signal** | What action got us this lead? | User-supplied | **25%** |
| **Trigger / intent** | Fresh event or intent at the employer? | `enrich_news` + `enrich_scoops` + `enrich_intent` | **15%** |

Weights overridable. Each axis 0–100; composite is the weighted sum.

## Tier + SLA (varies by use case)

SLA defaults below. `inbound_routing` is the live-triage motion where speed-to-lead dominates; other motions relax accordingly. Pick what fits — don't manufacture urgency the motion doesn't need.

| Tier | Composite | `inbound_routing` | `event_followup` / `pql_triage` | `content_follow_up` | Recommended action |
|---|---|---|---|---|---|
| **Hot 🔥** | ≥ 75 | < 5 min | < 1 hr | < 4 hr | Direct dial / personal outreach. Chain to `personalize-email`. |
| **Warm 🌤** | 50–74 | < 1 hr | same day | < 24 hr | SDR sequence with personalized opener. Multi-touch cadence. |
| **Cold ❄️** | < 50 | < 24 hr | < 48 hr | weekly nurture | Nurture cadence; tag for content drip; do not call. |

For high-intent sources (`demo_request`, `pricing_inquiry`, `free_trial`) in live-triage mode, fast response materially lifts qualification rate. Outside live-triage, the right SLA is longer.

## Resolution (four-bucket, lead-specific)

- **Auto-resolved** — high confidence; score immediately.
- **Verified** — match found with caveats (common name at large co); surface verification note.
- **Ambiguous** — multiple plausible matches, no clear winner; pause scoring.
- **Failed** — no match. **Never silently fall back to alternate identifier paths.**

Routing by type:
- **Numeric person ID** → auto-resolved.
- **Email** → `enrich_contacts(email)`. Email is a unique identifier. Match → auto-resolved. No match → failed. **Do NOT auto-route to name search** — a typo'd email (e.g., `[email protected]`) must not silently resolve to a different real person.
- **Name + company** → `enrich_contacts(firstName/lastName/companyName)`. Single high-accuracy match → auto-resolved. Multiple plausible → verified with note. No match → failed.
- **Free-text "John Smith at Acme"** → parse and route to name+company path.

100% resolution accuracy is the gate.

## Workflow

### 1. Pull GTM context (always)
`get_gtm_context(detailed: true)`. Capture personas, ICP, strategic priorities (for intent-topic curation).

### 2. Honor input data first
Use user-supplied source / weights / thresholds / use case. If `source` is missing on a multi-row list, ask once then default to `unknown` (50, flagged).

### 3. Resolve identifiers
Per the four-bucket rules. Batch in groups of ≤10 concurrent.

### 3.5. Relationship-context pre-flight (mandatory)

Tag each lead's **company** against GTM context:
- **`competitor`** ⚔️ — in `get_gtm_context.competitors`. Hard-warn — most inbound from competitors is talent or competitive intel.
- **`customer`** 🤝 — in `get_gtm_context.customers` / `proof_bank`. Reroute to `expansion` / `discovery_follow_up`.
- **`partner`** 🔗 — in `get_gtm_context.partners`. Co-sell framing.
- **`prospect`** — default.

The relationship tag appears in the headline before the tier emoji.

For Hot leads at `customer` or `competitor` companies: pause before pushing to cold-outbound AE; surface the routing question first.

### 4. Curate intent topics (only if trigger weight > 0)
From `get_gtm_context.strategicPriorities`, derive 5–10 topics via `lookup intent-topics fuzzyMatch=<theme>` — one call per theme. If no topics resolve, trigger weight = 0; redistribute.

### 5. Fetch data per lead (parallel, batched ≤10; chunked for large lists)
- `enrich_contacts(personId, fields: jobTitle, managementLevel, department, contactAccuracyScore, hasDirectPhone, hasMobilePhone, hasEmail, directPhone, mobilePhone, email)`.
- `enrich_companies(zoominfoCompanyId, fit-scoring fields)`.
- `enrich_news` + `enrich_scoops` for the employer — only if trigger weight > 0.
- `enrich_intent` with curated topics — only if trigger weight > 0.

**Batch + context-window discipline.** Process in **chunks of ~25 leads** end-to-end (resolve → fetch → score → compose row → write chunk → discard raw payloads) before moving to the next chunk. Don't accumulate full raw enrichment payloads for hundreds of leads in working context — once per-axis scores + the winning signal/topic strings are captured per lead, drop the rest. For >50-lead lists, summarize completed chunks into running totals (tier distribution, top-Hot list, missing-axes counts) and discard their per-lead breakdowns from context.

### 6. Score each axis

**Person fit (0–100)** — compare `enrich_contacts` to `get_gtm_context.buyerPersonas`:

| Dimension | Max | Banded |
|---|---|---|
| Management level | 30 | C = 30 · VP = 25 · Director = 18 · Manager = 10 · Non-Manager = 3 |
| Department | 25 | Primary persona dept = 25 · adjacent = 15 · unrelated = 0 |
| Job-title keyword | 20 | Exact = 20 · partial = 10 · none = 0 |
| Contact accuracy | 15 | ≥95 = 15 · 85–94 = 10 · 75–84 = 5 · <75 = 0 |
| Contact data completeness | 10 | email + direct + mobile = 10 · email + one phone = 7 · email only = 4 · none = 0 |

**Account fit (0–100)** — industry 30 · employee band 25 · revenue band 20 · geo 15 · business model 10.

**Source signal (0–100):**

| Source | Score |
|---|---|
| `demo_request` / `pricing_inquiry` | 100 |
| `free_trial` / `product_signup` | 90 |
| `content_download_high_intent` (comparison, RFP, pricing guide) | 75 |
| `webinar_attended` | 60 |
| `webinar_registered` | 50 |
| `content_download_low_intent` / `cold_inbound` | 35 |
| `newsletter_subscribe` | 25 |
| `unknown` | 50 (default; flag) |

**Trigger / intent (0–100)** — sa