lead-routing-rules

name	lead-routing-rules
description	Runbook for scoring and routing a new HubSpot lead to the right rep for {{projectName}} — territory matching, segment specialists, the stateless round-robin pool, intent scoring, HubSpot property writes, Slack notifications, and when to escalate an ambiguous lead to a human instead of guessing.

Turn a new inbound lead into an assigned rep before it goes cold. A 15-minute sweep reads HubSpot for leads on {{hubspot_lifecycle_stage}} that haven't been routed yet, scores each for intent, matches it against the territory map and segment specialists, and falls back to whichever rep in the round-robin pool has taken the fewest leads so far this week. The assigned owner and the reason are written back to HubSpot, the rep is notified in {{routing_channel}}, and high-intent leads are called out distinctly. A lead that doesn't clearly resolve — missing data, no matching rule, a genuine tie — is never guessed at; it goes to {{escalation_channel}} for a human to assign.

Fresh session per sweep — state lives on the HubSpot lead record itself (a kortix_routing_status property + timestamp + reason marks a lead handled), not in a local ledger file. The round-robin pool is stateless by design too: "whose turn is it" is answered by counting each rep's current lead load in HubSpot, not by a rotating pointer that would need to persist somewhere. A single sweep can find several new leads at once; handle each as an independent unit — a scoring or routing failure on one lead is logged and skipped, and never blocks or corrupts routing for any other lead in the same sweep.

- The 15-minute routing sweep fires. - A human asks the agent to route a specific lead, re-check HubSpot for new leads, or explain why a lead was routed where it was. - The territory map, segment specialists, or round-robin pool changes and needs to be reflected in the next sweep.

Step 0 — Orient: find what's new

Query HubSpot for contacts/leads on {{hubspot_lifecycle_stage}} that don't yet carry the routing marker:

GET /crm/v3/objects/contacts/search
  filterGroups: [
    { propertyName: "lifecyclestage", operator: "EQ", value: "{{hubspot_lifecycle_stage}}" },
    { propertyName: "kortix_routing_status", operator: "NOT_HAS_PROPERTY" }
  ]

Anything already carrying kortix_routing_status (whether routed or flagged) was handled by a prior run — skip it. A flagged lead stays skipped until a human resolves it directly in HubSpot (assigning an owner clears the need for another routing pass).

Step 1 — Read the fields the routing rules need

Pull, per lead: country/region, company size, industry, deal/budget estimate if present, job title, lead source, and any engagement data (page views, email opens, form fields submitted). These are the inputs to territory matching, segment matching, and intent scoring — a lead missing the fields a rule needs can't be matched on that rule.

Step 2 — Score intent

Signal	High-intent if
Title	VP-level or above, or an explicit buyer/economic-decision-maker title
Company size	At or above the team's enterprise threshold in memory
Stated timeline/budget	Filled in and inside the current quarter
Engagement	Multiple pricing-page visits, a demo request, or a direct sales-contact form (vs. a passive newsletter signup)

A lead is high-intent if it clears two or more of these. High-intent status doesn't change who it's routed to — it changes how the notification is flagged, so the assigned rep works it first.

Step 3 — Match the territory map

Check the lead's region/country against the territory-to-rep map kept in memory (e.g. "DACH → Rep A", "US-West → Rep B"). An exact match assigns that rep. If the region maps to more than one rule (an overlap in the map itself) or to no rule at all, this step doesn't resolve — move to Step 4.

Step 4 — Match the segment specialists

If territory didn't resolve, check company size and industry against the segment-to-specialist map in memory (e.g. "Enterprise (500+ employees) → Rep C", "Mid-market SaaS → Rep D"). A match assigns that rep. No match — move to Step 5.

Step 5 — Fall back to the round-robin pool

If neither territory nor segment resolved, route within the general round-robin pool defined in memory. Count each pool rep's leads currently owned with a kortix_routing_status of routed and a creation date in the current week; assign the new lead to whichever pool rep has the fewest. Ties break alphabetically by rep name — this keeps the pool stateless and reproducible without a rotating pointer to persist between sessions.

Step 6 — Escalate what doesn't resolve

A lead escalates instead of being assigned when:

• The region, company size, and industry fields needed to check the map are all missing or unusable.
• The territory map itself has a genuine overlap or gap for this lead (a data problem in the map, not the lead).
• The round-robin pool is empty or every pool rep is marked unavailable in memory.

Post the lead to {{escalation_channel}} with what was checked and why it didn't resolve. Set kortix_routing_status = flagged (with a timestamp and reason) so it isn't re-flagged on the next sweep.

Step 7 — Assign and write back

For a lead that resolved in Step 3, 4, or 5: set the HubSpot owner to the matched rep, and write kortix_routing_status = routed with a timestamp and the reason (e.g. "territory: US-West", "segment: enterprise", "round-robin: fewest current leads"). These are the only fields this skill ever writes.

Step 8 — Notify

Post to {{routing_channel}}: the lead (name, company, source), the assigned rep, and the routing reason. If the lead scored high-intent in Step 2, mark the notification clearly as high-intent so it's worked first. Escalated leads get their own post in {{escalation_channel}} instead, never a silent skip.

- **Never delete or merge.** This skill never removes a lead record or merges two records, under any circumstance — that action is entirely out of scope regardless of how confident a match is. - **Writes are scoped to routing.** The only HubSpot writes are the owner field and the `kortix_routing_status` property (with its reason and timestamp). No other field, no bulk update, ever. - **Ambiguous means escalate, never guess.** If territory, segment, and round-robin all fail to resolve cleanly, the lead goes to {{escalation_channel}} for a human — the agent never invents a fallback owner to close out the sweep. - **No duplicate routing.** Always check `kortix_routing_status` before scoring or routing — a lead handled once (routed or flagged) is never reprocessed, even across many sweeps. - **Round-robin is stateless.** "Whose turn it is" is computed fresh each sweep from each rep's current HubSpot lead count — never a pointer or counter that needs to survive between sessions. - **Scoped secrets.** The HubSpot connector is brokered server-side at runtime; no raw credential is ever pasted into chat.