<v2_changes_read_first>
v2.0.0 rebuilds this skill from a broken, never-installed v1.0.2 (it existed only as a zip with
a single file; its 6 vertical reference files, 4 connector cookbooks, champion-detection doc, and 2
Python scripts were referenced but never written, and its MCP tool names belonged to a different
environment). This version: (1) fixes every MCP tool name to what actually resolves in this
environment, (2) adds geo/language/rep_scope/named_owner_scope — this skill had zero
territory or rep-assignment concept before, only a single hardcoded "USA + Canada" default baked
into the SQL, (3) adds Production/Broadcast, Corporate AV, and Healthcare as 3 new verticals (9
total, up from 6), and (4) actually authors the previously-missing reference files and scripts.
See the Changelog at the bottom for the full list, and references/verticals/*.md for which of
the 9 verticals carry real deal/documented evidence vs. which are hypothesis-only.
</v2_changes_read_first>
<quick_start>
Trigger: "Build vertical list for [vertical]" or "Build all vertical lists" (M-F 6:30 AM ET via
scheduled task, per territory's own working hours — see the geo note below)
Inputs:
vertical— one or more of:higher-ed,community-colleges,live-events,courts-gov,houses-of-worship,k12,production-broadcast,corporate-av,healthcare.volume— default 35 callable leads per vertical (range 25-50).geo— one ofusa/canada/usa-canada(default, unchanged from v1.x) /uk/latam-spanish. Seereferences/geo-country-codes.mdfor the exact country sets and each geo's defaultlanguage. This replaces the old hardcoded US/Canada-only country filter — a UK or LatAm run before v2.0.0 silently returned zero rows.rep_scope(optional) — a seat key fromreferences/seats.md(edgar,nyasha,vasil). Resolves to that seat's territories + language and pre-scopes the pool; does not replace the vertical-pool model for NA runs where no rep_scope is given.named_owner_scope(optional) — a HubSpot owner id to INCLUDE-scope the whole pull to. For a UK run this resolves to Anthony Taroni's book, owner id165812850(resolved live viasearch_owners— seereferences/seats.md; he has no Nooks seat of his own, since Nyasha/Vasil work his book, not him). The architectural inverse of the AE-exclusion block below.- SDR owner_ids (optional) — if provided, prioritizes contacts already owned by these reps within the resolved pool; otherwise treats the pool as unassigned.
Outputs:
- HubSpot static list per vertical+geo:
Daily Call List - [Vertical] - [Geo] - YYYY-MM-DD - Google Sheet per vertical with ranked leads, ATL/BTL/Champion tags,
languagecolumn (en/es), vertical-specific intel column - Outcome sidecar:
~/.claude/skill-analytics/last-outcome-vertical-list-builder.json
Dependencies (this environment's actual tool names — v1.x's names do not resolve here):
mcp__claude_ai_Epiphan_Ai__execute_sql/ask_agent— HubSpot warehouse SQL + Clari callsmcp__claude_ai_Epiphan_Ai__hubspot_search_contacts/hubspot_search_companies/hubspot_get_contact/hubspot_get_company— entity lookups and live-write verificationmcp__claude_ai_Apollo_io__apollo_mixed_companies_search/apollo_mixed_people_api_search— greenfield prospecting + enrichmentmcp__claude_ai_Clay__find-and-enrich-contacts-at-company/find-and-enrich-list-of-contacts/get-task-context— phone/email waterfall (async — poll, don't assume a null means "not found")mcp__claude_ai_HubSpot__manage_crm_objects— the ONLY tool that can set a company's owner after creation (no equivalent exists in the Epiphan AI MCP); requires its own mandatory confirmation step before writing, per its own contract — never call it silently.- Google Drive MCP — for Sheets export
- Context7 — on-demand docs for any of the above when an API parameter shape is unclear </quick_start>
<house_rules> Customer-facing skill. Before output, run the gates in order (details: ~/.claude/skills/epiphan-house-rules-skill/reference/gates.md): S: search_product_catalog (Epiphan AI) or Epiphan Knowledge search before any product claim. B: check_my_copy on every customer-facing string. Q: qualify_lead right after the candidate pull, before tiering/enrichment/drafts. D: outbound text becomes a Gmail draft, never a send. Identifiers (owner IDs, portal, emails, seats) come from reference/identifiers.md in that skill — do not restate them here. On any gate failure follow reference/self-healing.md (retry, degrade with a flag, alert Tim, halt) and append a line to ~/.claude/skill-runs/.jsonl. </house_rules>
<golden_rules>
Inherited from bdr-ops/CLAUDE.md — these are non-negotiable gates. Apply BEFORE classification:
-
Customer Exclusion — drop
hubspot_contacts.lifecyclestageresolving to "Customer" -
Channel Partner Check — drop reseller-employee contacts (proAV, B&H, CDW, JB&A, Howard, DGI, Extron-Direct)
-
AE Exclusion with Reactivation Exception (CRITICAL) — by default, exclude contacts where
hubspot_owner_idis one of:82625923— Lex Evans190030668— Phillip Sandler
These are AEs Tim feeds demos to. SDR outbound to their actively-owned book causes double-touch and burns the relationship.
Reactivation Exception — an AE-owned contact CAN be re-added to a vertical list if BOTH conditions are true:
- No email contact in the last 90 days (
notes_last_contacted IS NULL OR notes_last_contacted < NOW() - INTERVAL '90 days') - No associated open deal (NOT EXISTS in
hubspot_deal_contactjoined tohubspot_dealswhere the deal is in any stage other than 'closedwon' or 'closedlost')
Greenfield Apollo dedupe must also apply this — if a greenfield contact's email matches an AE-owned HubSpot contact, run the same 90-day + no-deal test before deciding whether to drop or include.
-
ATL-First — when target volume is constrained, fill ATL slots before BTL slots
-
Geo Filter — respect the
geoargument (defaultusa-canada, unchanged) — resolved viareferences/geo-country-codes.mdandscripts/build_vertical_query.py, never a hardcoded literal in this file or a query again. -
Suppression — drop opted-out, hard-bounced, bad-address, and contacts touched within 2 days
-
Active Sequence Exclusion — drop contacts currently in an Apollo sequence (
prospecting_enrollments.status IN ('active','sending')) -
Named-owner scope is an INCLUSION filter, never an exclusion one (new in v2.0.0) — if
named_owner_scopeis set, the pool is filtered TO that owner's book, on top of (not instead of) rules 1-7. Seereferences/seats.md. </golden_rules>
<ae_exclusion_owners> Maintain this list as the single source of truth. Update if AE roster changes.
| Owner ID | Name | Role | |
|---|---|---|---|
| 82625923 | Lex Evans | AE | lexevans@epiphan.com |
| 190030668 | Phillip Sandler | AE | psandler@epiphan.com |
The full injected SQL clause (unchanged from v1.x) lives in scripts/build_vertical_query.py — do
not hand-retype it inline here or in a query; call that script and use its output.
When a contact is reactivated under this rule, tag it in the Google Sheet with Tier = REACTIVATED
(overrides the normal ATL/BTL/Champion bucket) so SDRs handle the conversation with extra care.
</ae_exclusion_owners>
Stage 1: Resolve Vertical + Territory Targets
Read the target vertical(s), geo, and optional rep_scope/named_owner_scope from the prompt.
| Vertical Argument | Reference File | Evidence |
|---|---|---|
higher-ed |
references/verticals/higher-ed.md |
Loss-derived (real) |
community-colleges |
references/verticals/community-colleges.md |
Documented (real ladder, no independent conversion study) |
live-events |
references/verticals/live-events.md |
Deal-derived (real, measured conversion) |
courts-gov |
references/verticals/courts-gov.md |
Hypothesis (lane proven, titles not individually ranked) |
houses-of-worship |
references/verticals/houses-of-worship.md |
Hypothesis, zero deal evidence — the least validated of the 9 |
k12 |
references/verticals/k12.md |
Deal-derived but thin (5 won / 3 lost titled) |
production-broadcast |
references/verticals/production-broadcast.md |
Documented (real ladder) — new in v2.0.0 |
corporate-av |
references/verticals/corporate-av.md |
Documented (real ladder) — new in v2.0.0 |
healthcare |
references/verticals/healthcare.md |
Deal-derived, real sample (56 won / 18 lost) — new in v2.0.0 |
If "all" or no specific vertical is named, run all 9 in parallel.
If rep_scope is given, resolve it against references/seats.md FIRST — it determines the
effective geo (and, for Edgar, potentially more than one) and the default language before
Stage 2 runs. If named_owner_scope is given but no real owner id has been supplied yet (Anthony
Taroni's case as of this writing), treat it as a no-op and say so in the run's output rather than
silently filtering to nothing.
Stage 2: HubSpot-Owned Pull (Primary Source)
For each vertical+geo combination, get the query from scripts/build_vertical_query.py rather than
hand-writing SQL inline:
python3 scripts/build_vertical_query.py <vertical> --geo <geo> [--named-owner-id <id>]
Run the printed SQL via mcp__claude_ai_Epiphan_Ai__execute_sql. Keep any manual follow-up query
under ~1500 chars to stay clear of the tool's char limit — split into CTEs if needed.
Query B: Champion Signals — see references/champion-detection.md for the full 3-signal logic
(job-changer alumni / high HubSpot engagement / past Clari call participant). These signals are
territory-agnostic — they key off Epiphan's own global CRM history, not a geo-specific table.
Champions are the highest-priority slots in the daily list — top of the dial queue regardless of ATL/BTL.
Stage 3: ATL / BTL Classification (Vertical- AND Language-Specific)
Use scripts/classify_vertical.py:
python3 scripts/classify_vertical.py <vertical> "<title>" [geo]
It runs the vertical's English rubric always, and its Spanish rubric too only when geo == "latam-spanish" — running a Spanish rubric against a purely English-market title is unsafe (a
bare Spanish executive pattern can accidentally match an English acronym like "CEO" and override a
deliberate English-ladder tier; found and fixed during this rebuild — see the script's own
docstring). Not every vertical has a ported Spanish rubric yet (Houses of Worship, Community
Colleges, Production/Broadcast, Healthcare are EN-only for now) — that is not a bug.
Classification order (unchanged from v1.x):
- Champion (any of the 3 signals) → tier =
CHAMPION, regardless of title - Reseller employee (company_is_reseller + senior title) →
CHANNEL(excluded from list) - Vertical-specific ATL (from reference file) →
ATL(tier 5,TIER_ECONOMIC_BUYER) - Vertical-specific BTL (from reference file) →
BTL(tier 4,TIER_CHAMPION) - Technical validator → tier 3, pair with a champion, never carry alone
- NEVER patterns (see each vertical's reference file) → drop entirely — reject explicitly, never let a hard-reject title fall through as a generic "no match"
- Else →
TIER_OPENER/TIER_LOW_YIELD(keep, don't drop — a BDR can disqualify later)
Set the language column from classify_vertical.py's winning-language note ([en]/[es]),
falling back to the geo's default language (references/geo-country-codes.md) if the title was
blank/unclassifiable. This is what flags a Spanish lead for Edgar's Spanish-language call scripts
and Clay enrichment prompts, per this rebuild's original ask.
Stage 4: Greenfield Fill (Apollo) — IF HubSpot bucket short
If post-classification HubSpot universe yields fewer than the target ATL count, fill the gap from
Apollo. Use mcp__claude_ai_Apollo_io__apollo_mixed_companies_search and
apollo_mixed_people_api_search. Per-vertical filters live in each references/verticals/*.md's
own "Apollo search filters" section; organization_locations is resolved from the run's geo, not
hardcoded. See references/connectors/apollo-cookbook.md for the greenfield-dedupe procedure
(against both the AE-exclusion set and, if set, named_owner_scope) and the Spanish-title-search
caveat (search Apollo on accent-safe stems, not full accented phrases — classify locally after).
If unsure about Apollo filter syntax, query Context7:
Use mcp__Context7__resolve-library-id with query "apollo.io api"
Then mcp__Context7__get-library-docs to pull the relevant section
Stage 5: Phone/Email Enrichment (Clay Waterfall)
For any greenfield contact lacking a phone, run the Clay waterfall per
references/connectors/clay-cookbook.md — enrichment is async, poll get-task-context with the
specific entityIds you selected, don't assume a null means unresolved forever (clay_negative _cache is a real final answer, don't re-spend on it). Drop contacts that come back phone-less
after Clay — not callable today, queue for re-enrichment tomorrow.
Stage 6: Rank + Slot
Within each vertical+geo bucket, rank contacts by:
- Champions (any signal) — top of list
- ATL with verified phone — by company size descending, then by
lastmodifieddate(freshest) - ATL without phone (post-Clay) — drop to bottom unless bucket is short
- BTL with verified phone — by company size, then by recency
- Anything else — drop
Slot to target volume (default 35, range 25-50). Mix should land near 40% ATL / 40% BTL / 20% Champion. A Champion count < 5 is normal — don't force-promote BTLs to fill that slot.
Stage 7: Output
Output 1: HubSpot Static List
Daily Call List - [Vertical] - [Geo] - YYYY-MM-DD (geo added to the name in v2.0.0 so an Edgar
LatAm list and an NA list for the same vertical never collide). Add selected contact IDs via
mcp__claude_ai_HubSpot__manage_crm_objects if list management is exposed there; otherwise
document the contact IDs for a one-time manual list creation.
Output 2: Google Sheet
Tier | Champion Signal | First | Last | Title | Company | Phone | Email |
HubSpot URL | Vertical Intel | Last Touch | Days in System | Owner | Language | Geo
Language and Geo are new columns in v2.0.0. The "Vertical Intel" column pulls a one-sentence
"why now" hook from the vertical's reference file — several verticals (Houses of Worship,
Production/Broadcast, Healthcare) have NO validated hook yet; use their generic placeholder rather
than inventing a seasonal one.
Output 3: Sidecar
Write ~/.claude/skill-analytics/last-outcome-vertical-list-builder.json:
{
"ts": "ISO8601",
"skill": "vertical-list-builder",
"version": "2.0.0",
"verticals_run": ["higher-ed", "k12"],
"geo": "usa-canada",
"rep_scope": null,
"metrics": {
"higher-ed": {"target": 35, "delivered": 35, "atl": 14, "btl": 15, "champion": 6,
"greenfield_fill": 8, "language_mix": {"en": 35, "es": 0}},
"k12": {"target": 35, "delivered": 32, "atl": 12, "btl": 18, "champion": 2,
"greenfield_fill": 12, "language_mix": {"en": 32, "es": 0}}
},
"alerts": [],
"runtime_ms": 0,
"session_id": "YYYY-MM-DD"
}
language_mix is new in v2.0.0 — a latam-spanish run that comes back entirely en is itself an
alert-worthy signal (something upstream may be translating titles, or the Spanish rubric isn't
firing), same discipline mexico_personas.language_mix() uses in the sibling repo.
Stage 8: Alerts
| Alert | Threshold | Level |
|---|---|---|
| Vertical bucket under target | delivered < 25 | ⚠️ Warning |
| ATL share below 30% | atl/delivered < 0.30 | ⚠️ Warning |
| Greenfield fill > 50% | greenfield/delivered > 0.50 | 🔍 Review (HubSpot book is depleting) |
| Clay enrichment failure rate > 30% | unverified/attempted > 0.30 | 🚨 Critical (waterfall broken) |
| Champion count = 0 across all verticals | sum(champion) = 0 | 🔍 Review (signal logic might be misfiring) |
A latam-spanish run's language_mix is 100% en |
new in v2.0.0 | 🔍 Review — Spanish rubric may not be firing, or titles are pre-translated upstream |
named_owner_scope was requested but no real owner id exists yet |
new in v2.0.0 | ⚠️ Warning — ran unscoped, say so explicitly, don't silently return the full pool as if it were scoped |
<success_criteria>
- Every requested vertical/territory bucket returns 25-50 callable contacts (phone verified via Apollo → Clay waterfall), or a zero-with-reason line naming the empty stage
- Every contact carries an ATL / BTL / Champion tier derived from the vertical's own decision-maker patterns in the title's language, never generic seniority
- Golden Rules applied: no customers (device_count >= 1), no channel partners, no AE-owned contacts with activity < 90 days, no suppressed leads
- Output delivered as a HubSpot static list AND a Google Sheet tagged with Vertical, Territory, Language, Tier columns
- Seat scope resolved from
references/seats.mdat run time, never hardcoded rep names - Outcome sidecar written to
~/.claude/skill-analytics/last-outcome-vertical-list-builder.json</success_criteria>
Working with Connectors
This skill chains 4 different MCPs. When you hit a parameter or response shape you don't recognize, always probe Context7 before guessing — misshaping an Apollo or Clay call burns credits and silently produces wrong leads.
For deeper guidance on each connector, read:
references/connectors/hubspot-warehouse.md— warehouse schema, common joins, and the real traps found building this rebuild (LEFT JOIN + COUNT(*), subdomain matches, owner-write gaps)references/connectors/apollo-cookbook.md— search filters, greenfield dedupe, Spanish-title search caveatsreferences/connectors/clay-cookbook.md— async enrichment states, wrong-person riskreferences/champion-detection.md— the 3-signal logic, territory-agnostic by designreferences/geo-country-codes.md— the geo → country/language lookup every other file readsreferences/seats.md— rep → territory → language, and the Anthony-Taroni-id gap
Failure Modes + Recovery
| Failure | Recovery |
|---|---|
execute_sql query too long |
Split into 2-3 sub-queries chained via CTE |
execute_sql timeout |
Retry simpler; if still timing out, drop the join causing the most rows |
| Apollo returns 0 results for greenfield | Loosen person_seniorities first, then organization_num_employees_ranges |
| Clay returns 0 phones | Verify the input contact has a verified email; Clay needs an anchor |
| HubSpot list creation fails | Fall back to writing contact IDs to the Sheet's "HubSpot Bulk Add" tab |
| Vertical universe < 50 raw contacts | Don't fail — emit warning, run greenfield fill more aggressively |
| A geo run returns 0 rows | Check references/geo-country-codes.md's country set actually matches this run's geo — a silent 0 was v1.x's core bug; never assume 0 means "no real accounts there" without checking the filter first |
named_owner_scope set but resolves to 0 rows |
Confirm the owner id is real and active (not a departed rep) before concluding the book is empty |
Changelog
v2.0.0 (2026-09-12) — Territory/language rebuild, 9 verticals, actually installed
- Extracted the never-installed v1.0.2 zip to
~/.claude/skills/vertical-list-builder/— it previously existed nowhere runnable. - Fixed every MCP tool name from a different environment's connector-hash naming to this environment's actual names.
- Added
geo(usa/canada/usa-canada/uk/latam-spanish) — replaces the hardcodedcountry IN ('United States','Canada','US','CA')SQL literal, which silently returned zero rows for any non-US/Canada run. Newreferences/geo-country-codes.mdis the single lookup. - Added
language(en/es) to the contact schema, Sheet, and JSON sidecar — did not exist anywhere in v1.x. Derived fromgeo, with per-contact override. - Added
rep_scope(newreferences/seats.md, mirroring the sibling repo'sconfig/sdr_seats.jsonpattern) — represents Edgar's USA+Canada+LatAm scope and Nyasha's Canada+UK dual-territory scope. v1.x had zero rep→territory concept at all. - Added
named_owner_scope— an inclusion filter (architectural inverse of the existing AE-exclusion block) for a named account owner's book (Anthony Taroni's UK case). Resolved live viasearch_ownerssame day: owner id165812850, no Nooks seat of his own. - Added 3 verticals: Production/Broadcast, Corporate AV, Healthcare (9 total, up from 6) —
ported from the sibling
epiphan-lead-harvesterrepo'spersona_ladder.py, which already had real ladders for all three that this skill simply never used. - Authored all previously-missing dependencies: 9
references/verticals/*.md, 3references/connectors/*.md,references/champion-detection.md,references/geo-country- codes.md,references/seats.md,scripts/classify_vertical.py,scripts/ build_vertical_query.py. - Found and fixed two real bugs while spot-checking the new scripts (per this rebuild's own
verification step): (1) running a Spanish rubric unconditionally let a bare
CEOacronym match override an English ladder's deliberate founder-trap demotion — fixed by scoping Spanish rubric consultation tolatam-spanishruns only; (2) the Corporate AV ladder (ported frompersona_ladder.py, a bug present in the SOURCE too, not introduced here) never matched "audiovisual" spelled out, only bare "av" — fixed here; not yet fixed in the sibling repo's ownpersona_ladder.py, flag that back if this skill's fix should be ported upstream too.
v1.0.2 (2026-04-29) — AE reactivation exception (unchanged, see prior history below)
- Softened "AE Hard-Exclude" to "AE Exclusion with Reactivation Exception"
- AE-owned contacts can re-enter vertical lists if BOTH:
notes_last_contactedis NULL or > 90 days old, AND no open deal exists inhubspot_deal_contact - Reactivated contacts get
Tier = REACTIVATEDtag in output (overrides ATL/BTL/Champion)
v1.0.1 (2026-04-29) — AE hard-exclude
- Promoted "AE-owned <90d" Golden Rule to "AE Hard-Exclude"
- Added explicit
<ae_exclusion_owners>block as single source of truth for AE roster
v1.0.0 (2026-04-29) — Initial release (never actually installed until v2.0.0)
- 6 verticals: Higher Ed, Community Colleges, Live Events, Courts/Gov, Houses of Worship, K-12
- Vertical-first architecture (SDR-agnostic) — list belongs to vertical, any SDR can work it
- Champion detection via 3 signals (job-changer, engagement, Clari participant)
- HubSpot-first sourcing → Apollo greenfield fill → Clay phone enrichment
- Default geo USA + Canada, hardcoded
- Outputs HubSpot static list + Google Sheet per vertical
- Inherits Golden Rules from bdr-ops/CLAUDE.md
- Hard target: 25-50 callable per vertical per day, ~40/40/20 ATL/BTL/Champion mix
Roadmap (v2.1+ candidates)
- Supply Anthony Taroni's real HubSpot owner id — resolved 2026-09-12:
165812850, no Nooks seat.named_owner_scopecan filter for real now. - Supply Nyasha Chigwedere's real HubSpot owner id — resolved 2026-09-12:
94135434, Nooks userLGCdlTv6v8dSAiSsoJ7ETWQHVKl1. - Resolve whether Nyasha's Canada scope is a handoff from Edgar or an addition (see
references/seats.md's open question). - Port this rebuild's
corporate-avword-order fix (bare "av" missing "audiovisual") back upstream into the sibling repo'spersona_ladder.py. - Build a Spanish rubric for Houses of Worship, Community Colleges, Production/Broadcast, and Healthcare if a LatAm run ever needs one of those verticals — currently EN-only.
- Auto-suppress contacts that didn't connect after 5 dial attempts (cold list rotation)
- Vertical-specific email templates auto-attached to Sheet (one-touch SDR launch)
- Slack daily digest posted to #sdr-team channel with bucket-level metrics
- Win-loss-aware re-targeting (drop verticals/sub-segments where win rate < 5%)