phone-verification-waterfall

What this skill does

<objective>
Maintain a continuously refreshed inventory of callable leads with verified phone numbers. Automates the waterfall from HubSpot lead identification → Apollo phone verification → Clay enrichment (for Apollo misses) → HubSpot sync. Ensures Tim ALWAYS has 50+ verified dial prospects queued and ready, eliminating "nobody to call" downtime and maximizing daily dial velocity.

Built on: Lead lifecycle → phone verification → queue prioritization by ICP + intent signals.
</objective>

<quick_start>
**Standalone run (manual trigger):**
"verify phones" or "phone waterfall" or "callable leads" or "who can I call" → pulls all HubSpot leads missing phones → enriches via Apollo + Clay → writes back to HubSpot → outputs sortable callable queue

**Scheduled run:**
Every Monday & Wednesday 6:15 AM (between prospect-enrich 6:00 AM and prospect-refresh 6:30 AM) — keeps phone inventory fresh twice-weekly and allows newly refreshed leads to be phone-verified before daily calls

**Trigger phrases:**
- "verify phones"
- "phone waterfall"
- "callable leads"
- "who can I call"
- "dial list"
- "always have someone to call"
- "phone check"
- "enrich phones"
</quick_start>

<success_criteria>
- HubSpot lead pull returns 100+ contacts missing phones from all ICP verticals
- Apollo phone lookup succeeds for 40-50% of contacts (baseline)
- Clay waterfall fills 60-70% of remaining Apollo misses
- HubSpot phone field updated for 70%+ of missing numbers
- Final callable queue contains 50+ contacts sorted by ICP score + intent
- Zero contacts belong to customers (lifecycle_stage = 'customer') — Golden Rules block them
- Zero contacts owned by Account Executives (Lex, Phil, Ron, Anthony) — no AE lead theft
- Zero channel partners or existing device owners included
- Execution time under 8 minutes (HubSpot → Apollo → Clay → sync)
</success_criteria>

<workflow>

## Pipeline Stages

```
STAGE 1: PULL LEADS          STAGE 2: APOLLO PHONE      STAGE 3: CLAY WATERFALL    STAGE 4: HUBSPOT SYNC    STAGE 5: CALLABLE QUEUE
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
HubSpot Query       →     Apollo People Match    →    Clay Enrichment       →   Update Phone Field   →    Prioritized CLI
phone = null/empty  →     (Name + Email + Org)   →    (Multiple Providers)  →   (API bulk update)    →    ICP Score Sort
lifecycle_stage     →     Return: Verified #     →    Return: Verified #    →   Mark: enriched_at    →    Intent Signals
!= 'customer'       →     Success Rate: 40-50%   →    Success Rate: 30-40%  →   (Contact & Company) →    Output: CSV + Chat
No Excluded Owner   →     (No cost)              →    (Find + Enrich)        →   Log completion       →    Time-to-dial: <5s
Golden Rules Pass   →                            →                          →                        →
```

## Stage 1: Pull Leads Needing Phones

**HubSpot Query:**
```
Criteria (ALL must match):
- phone IS NULL OR phone = '' (empty string)
- lifecyclestage != 'customer'
- AE-owned (82625923, 423155215, 190030668): EXCLUDE if <90d activity. KEEP as STALE AE LEAD if >90d inactive (Tim reviews ATL/BTL + value). Ron=all, Lex/Phil=NA only.

Golden Rules Hard Gate (SKIP if ANY match):
- first_conversion contains ['Pearl', 'setup', 'Connect', 'signup']
  (Existing product engagers — not cold prospects)
- company.device_count >= 1
  (Already owns equipment — likely existing relationship)
- is_channel = true
  (Channel partners excluded)
- engagement_overview contains ['Pearl', 'trial', 'demo', 'customer']
  (Existing touchpoints)
```

### ATL/BTL Classification Gate (applied after Golden Rules)
Classify each contact by job title using approved ATL/BTL definitions (see CLAUDE.md § ATL/BTL Classification v1.0):

**ATL Title Keywords (budget authority — PRIORITY DIAL):**
Chief (CIO, CTO, CFO, COO) • VP (AVP, SVP, EVP) • President • Provost • Vice Provost • Superintendent • Director (of IT, Technology, Facilities, Academic Technology, Procurement, Materials Mgmt, Medical Education, Court Administration) • Dean • Court Administrator • Clerk of Court • City Manager • County Manager • Senior Pastor • Executive Pastor

**BTL Title Keywords (no budget authority — LOWER PRIORITY):**
Technician • Specialist • Coordinator • Support • Administrator (Systems/Network/Database) • Engineer (AV/Network/Systems) • Operator • Instructor/Professor/Faculty • Designer • Assistant • Clerk (non-Court Admin) • Volunteer • Intern • Student • Resident • Help Desk

**NEVER ATL — Auto-classify BTL regardless of other signals:**
Warehouse Manager • Network Manager • Systems Administrator • AV Technician • Graphic Design Instructor • Program Administrator • Web Designer • Classroom Support • Lab Coordinator • Maintenance • Building Engineer • Multimedia Services Manager • Video Production Specialist • Streaming Crew

**Gray Zone — Flag for manual review:**
Manager (AV/Facilities/IT) — ATL only if reports to Director+ AND has delegated budget >$25K
Department Chair • Program Director • Director of Educational Technology

Tag each contact: `atl_btl_tier = 'ATL' | 'BTL' | 'GRAY'`

**Output:** Unsorted list of 100+ contacts with:
- contact_id (HubSpot)
- first_name, last_name
- email (primary business email)
- company_name
- hs_job_title
- hubspot_owner_id, hubspot_owner_name
- company.industry, company.num_employees, company.hs_lead_status
- first_conversion (for Golden Rules check)

**Tool:** `hubspot_search_contacts` with filters applied

</Stage 1>

## Stage 2: Apollo Phone Lookup

**For each contact from Stage 1, run in parallel batches:**

```
Input:  contact_id, first_name, last_name, email, company_name
        ↓
apollo_people_match(
  first_name: "{first_name}",
  last_name: "{last_name}",
  email: "{email}",
  organization_name: "{company_name}",
  domain: "{company_domain}",
  reveal_personal_emails: false
)
        ↓
Output: phone (mobile_phone or corporate_phone, verified)
        ↓
Match rate: 40-50% success (Apollo baseline)
        ↓
NO COST — Apollo is included free
```

**Logic:**
- Apollo returns mobile_phone or corporate_phone (both acceptable for dial)
- If phone returned: tag contact `apollo_phone_source = true`
- If no phone: move to Stage 3 (Clay waterfall)
- Keep all results for final merge

**Tool:** `apollo_people_match` (batch parallel)

</Stage 2>

## Stage 3: Clay Waterfall Enrichment

**For contacts where Apollo returned NO phone, use Clay:**

**Option A: Company-level enrichment (recommended for speed)**
```
find-and-enrich-contacts-at-company(
  companyIdentifier: "{company_domain}",
  contactFilters: {
    job_title_keywords: extracted from hs_job_title,
    locations: optional if available
  },
  dataPoints: {
    contactDataPoints: [
      { type: "Email" },
      { type: "Summarize Work History" }
    ]
  }
)
```

Then for contacts found, run `add-contact-data-points` to enrich phones:
```
add-contact-data-points(
  taskId: "{from find-and-enrich response}",
  dataPoints: [
    { type: "Custom", customDataPoint: "phone number from multiple providers" }
  ],
  entityIds: [extracted contact IDs]
)
```

**Option B: Direct contact enrichment (if company approach yields few)**
```
find-and-enrich-list-of-contacts(
  contactIdentifiers: [
    {
      contactName: "{first_name} {last_name}",
      companyIdentifier: "{company_domain}"
    }
  ],
  dataPoints: {
    contactDataPoints: [
      { type: "Custom", customDataPoint: "verified phone number" }
    ]
  }
)
```

**Expected yield:**
- 30-40% of Apollo misses will get phones via Clay
- Combined success rate: 40-50% (Apollo) + 30-40% of remainder (Clay) ≈ 65-70% total

**Cost:** Clay credits consumed (monitor spend against monthly allocation)

**Tool:** `find-and-enrich-contacts-at-company` or `find-and-enrich-list-of-contacts`

</Stage 3>

## Stage 4: HubSpot Sync

**For all contacts with verified phones (Apollo + Clay combined):**

```
Batch update HubSpot contacts:
For each contact:
  UP