phone-verification-waterfall

维护一份持续更新的可拨打潜在客户清单，并验证其电话号码。自动完成以下流程：在 HubSpot 中识别潜在客户 → 通过 Apollo 验证电话号码 → 为 Apollo 未找到号码的联系人使用 Clay 补充信息 → 同步回 HubSpot。确保 Tim 始终有 50+ 个已验证、排队就绪的拨号对象，避免因“无电话可打”而停工，并最大限度提高每日拨号效率。

基于：潜在客户生命周期 → 电话号码验证 → 按 ICP + 意向信号排序队列。

<quick_start> 独立运行（手动触发）： “verify phones”或“phone waterfall”或“callable leads”或“who can I call” → 提取 HubSpot 中所有缺少电话号码的潜在客户 → 通过 Apollo + Clay 补充信息 → 写回 HubSpot → 输出可排序的可拨打队列

定时运行： 每周一和周三上午 6:15（在上午 6:00 的 prospect-enrich 与上午 6:30 的 prospect-refresh 之间）——每周更新两次电话号码清单，并确保新刷新的潜在客户能在每日拨号前完成电话验证

触发短语：

• “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 潜在客户提取结果包含来自所有 ICP 垂直领域的 100+ 个缺少电话号码的联系人
• Apollo 电话号码查询成功率达到 40-50%（基准值）
• Clay 瀑布流程补全 Apollo 未找到号码的联系人中的 60-70%
• HubSpot 电话号码字段更新覆盖 70%+ 的缺失号码
• 最终可拨打队列包含 50+ 个联系人，并按 ICP 评分 + 意向排序
• 不包含任何客户联系人（lifecycle_stage = 'customer'）——黄金规则会将其拦截
• 不包含任何由客户经理（Lex、Phil、Ron、Anthony）负责的联系人——不得抢占客户经理的潜在客户
• 不包含任何渠道合作伙伴或现有设备所有者
• 执行时间不超过 8 分钟（HubSpot → Apollo → Clay → 同步） </success_criteria>

流水线阶段

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   →                            →                          →                        →

阶段 1：提取缺少电话号码的潜在客户

HubSpot 查询：

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 分类关卡（在应用黄金规则后执行）

根据职位名称，使用获准的 ATL/BTL 定义对每位联系人进行分类（参见 CLAUDE.md § ATL/BTL Classification v1.0）：

ATL 职位关键词（拥有预算决策权——拨号优先级高）： Chief（CIO、CTO、CFO、COO）• VP（AVP、SVP、EVP）• 总裁 • 教务长 • 副教务长 • 学区总监 • Director（IT、Technology、Facilities、Academic Technology、Procurement、Materials Mgmt、Medical Education、Court Administration）• 院长 • 法院行政主管 • 法院书记员 • 市经理 • 县经理 • 高级牧师 • 执行牧师

BTL 职位关键词（无预算决策权——拨号优先级低）： 技术员 • 专员 • 协调员 • 支持人员 • 管理员（Systems/Network/Database）• 工程师（AV/Network/Systems）• 操作员 • 讲师/教授/教职员工 • 设计师 • 助理 • 文员（非法院行政人员）• 志愿者 • 实习生 • 学生 • 住院医师 • Help Desk

绝不归为 ATL——无论其他信号如何，均自动分类为 BTL： 仓库经理 • 网络经理 • 系统管理员 • AV 技术员 • 平面设计讲师 • 项目管理员 • 网页设计师 • 教室支持人员 • 实验室协调员 • 维修人员 • 楼宇工程师 • 多媒体服务经理 • 视频制作专员 • 流媒体团队

灰色地带——标记以供人工审核： 经理（AV/Facilities/IT）——只有在其向 Director+ 汇报且获授权预算 >$25K 时，才归为 ATL 系主任 • 项目主任 • 教育技术 Director

为每位联系人添加标签：atl_btl_tier = 'ATL' | 'BTL' | 'GRAY'

输出： 包含 100+ 个联系人的未排序列表，其中包含：

• contact_id（HubSpot）
• first_name、last_name
• email（主要商务邮箱）
• company_name
• hs_job_title
• hubspot_owner_id、hubspot_owner_name
• company.industry、company.num_employees、company.hs_lead_status
• first_conversion（用于检查黄金规则）

工具： hubspot_search_contacts，并应用相应筛选条件

</Stage 1>

阶段 S — 抑制筛选

在投入电话信息补充成本之前，排除被抑制的联系人：

• 排除：bdr_suppression_until 已设置，且 bdr_suppression_until > 今天
• 纳入：bdr_suppression_until 未设置（从未被抑制）
• 纳入：bdr_suppression_until < 今天（冷却期已结束）

HubSpot 筛选条件：propertyName: "bdr_suppression_until", operator: "NOT_HAS_PROPERTY" 或 operator: "LT", value: TODAY_ISO 参考：lead-suppression-spec（bdr_suppressed、bdr_suppression_reason、bdr_suppression_until）

---

阶段 2：Apollo 电话查找

对阶段 1 中的每位联系人，分批并行运行：

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

逻辑：

• Apollo 会返回 mobile_phone 或 corporate_phone（两者均可用于拨打）
• 如果返回电话号码：为联系人添加标签 apollo_phone_source = true
• 如果没有电话号码：转到阶段 3（Clay 信息瀑布流）
• 保留所有结果，以便最终合并

工具：apollo_people_match（批量并行）

</Stage 2>

阶段 3：Clay 瀑布流信息补充

对于 Apollo 未返回电话号码的联系人，使用 Clay：

选项 A：公司级信息补充（推荐，速度更快）

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" }
    ]
  }
)

然后对找到的联系人运行 add-contact-data-points，以补充电话号码：

add-contact-data-points(
  taskId: "{from find-and-enrich response}",
  dataPoints: [
    { type: "Custom", customDataPoint: "phone number from multiple providers" }
  ],
  entityIds: [extracted contact IDs]
)

选项 B：直接补充联系人信息（如果公司方式找到的联系人较少）

find-and-enrich-list-of-contacts(
  contactIdentifiers: [
    {
      contactName: "{first_name} {last_name}",
      companyIdentifier: "{company_domain}"
    }
  ],
  dataPoints: {
    contactDataPoints: [
      { type: "Custom", customDataPoint: "verified phone number" }
    ]
  }
)

预期产出：

• Apollo 未找到电话号码的联系人中，有 30-40% 可通过 Clay 获取电话号码
• 综合成功率：Apollo 为 40-50% + Clay 从剩余联系人中获取 30-40% ≈ 总计 65-70%

**成本：**消耗 Clay 积分（请对照每月额度监控支出）

工具：find-and-enrich-contacts-at-company 或 find-and-enrich-list-of-contacts

</Stage 3>

阶段 4：HubSpot 同步

针对所有已验证电话号码的联系人（合并 Apollo 和 Clay 的结果）：

Batch update HubSpot contacts:
For each contact:
  UPDATE contact {contact_id}
  SET:
    phone = "{verified_phone}"
    phone_source = "apollo" OR "clay" (track origin)
    phone_verified_at = NOW()
    phone_waterfall_pass = true

Log event to company:
  ADD ACTIVITY: "Phone verified via Apollo/Clay waterfall"
  (Creates audit trail for Sales)

同步策略：

• 使用 HubSpot API 分批处理（每批 500 位联系人）
• 添加 phone_source 标签（apollo、clay、manual）
• 添加 phone_verified_at 时间戳标签
• 如果联系人有关联的商机或公司对象，则将完成情况记录到该对象

**工具：**通过 hubspot_update_contact（逐个联系人；没有批量 MCP 工具）或直接 HTTP 调用 HubSpot REST API（联系人批量更新）

</Stage 4>

阶段 5：可拨打队列与优先级排序

按以下顺序对最终输出排序：

1. **ATL/BTL 层级（主要）：**ATL 联系人优先，然后是 GRAY，最后是 BTL

2. ICP 垂直行业评分（次要）：

   Higher Ed ..................... 90
   Courts/Legal ................... 85
   Government ..................... 80
   Corporate AV ................... 80
   Healthcare ..................... 75
   Houses of Worship .............. 70
   K-12 Schools ................... 65
   

3. 意向信号（第三优先级）：

   • 正在招聘 AV/IT 岗位：+15 分
   • 近期有设施扩建新闻：+10 分
   • 技术栈显示 AV 设备已过时（Extron、Matrox 替换信号）：+12 分
   • 已发布 RFP 或采购活动：+10 分
   • 网站提到工作室/控制室/广播：+8 分
   • 近期融资/收购：+5 分

4. 近期互动情况（第四优先级）：

   • 30 天内有过互动：队列靠前
   • 31-60 天内有过互动：队列中间
   • 近期无互动：队列靠后（但仍可拨打）

最终可拨打队列格式：

完整的 ASCII 队列输出模板（摘要区块、可立即拨打的表格、拨号器快捷链接、后续步骤）请参阅 reference/callable-queue-format.md。

输出格式：

• **聊天：**包含 ICP 评分前 10-20 名的格式化表格（模板见 reference/callable-queue-format.md）
• **CSV 下载：**包含所有数据的完整队列，可导入 dialpad/Aircall
• **按垂直行业查看：**按行业分组的次级视图，用于垂直行业拓展
• **集成：**提供将队列导入 Dialpad、Aircall 或销售互动工具的链接

**工具：**根据阶段 4 的输出进行汇总、排序、格式化并展示

</Stage 5>

回复扫描集成

通过回复扫描自动加入队列（上午 10 点、下午 1 点、下午 3 点）：

当回复扫描发现缺少电话号码的新潜在客户时：

• 这些潜在客户会自动加入下一次计划的电话瀑布运行队列（星期一或星期三上午 6:15）
• 采用标准丰富工作流（Apollo → Clay 瀑布流程 → HubSpot 同步）

紧急高 ICP 潜在客户处理：

• 对于 ICP 评分达到 80+ 且被认定为高优先级的潜在客户，立即触发单联系人 Apollo 查询
• 如果 Apollo 查询成功，将电话号码添加到联系人记录，并加入当天的拨号队列
• 如果 Apollo 查询失败，则留待下一次计划的瀑布流程运行（标准工作流）

逻辑：

IF reply_scan_found_lead AND lead.phone IS NULL
  IF lead.icp_score >= 80 AND lead.priority = 'high'
    → TRIGGER immediate apollo_people_match(lead)
    → IF success: append phone, mark urgent_dial = true
    → ELSE: queue for next waterfall run
  ELSE
    → Queue for next scheduled waterfall (Mon or Wed 6:15 AM)

这样可以确保紧急潜在客户当天即可拨打，同时通过批量丰富处理标准潜在客户，保持效率。

计划自动化

Cron： 每周一和周三上午 6:15（UTC 或 Tim 的本地时区）

MONDAY MORNING SEQUENCE:
6:00 AM  → bdr-v3-prospect-enrich (refresh prospect company data)
6:15 AM  → phone-verification-waterfall-skill (verify phones on refreshed data)
6:30 AM  → bdr-v3-prospect-refresh (refresh deal velocity metrics)

WEDNESDAY MORNING SEQUENCE (mid-week refresh):
6:00 AM  → bdr-v3-prospect-enrich (refresh prospect company data)
6:15 AM  → bdr-v3-phone-waterfall-midweek (verify phones on mid-week refreshed data)
6:30 AM  → bdr-v3-prospect-refresh (refresh deal velocity metrics)

为什么安排在每周一和周三上午 6:15？

• 星期一： 周日晚上进行的潜在客户调研会将新潜在客户录入 HubSpot；上午 6:00 丰富数据，确保公司概况数据保持最新；上午 6:15 验证电话号码，趁这些潜在客户信息仍新鲜时完成处理；上午 6:30 刷新销售进度，让 Tim 在首次拨打电话前掌握完整情况
• 星期三： 周中刷新潜在客户，纳入周二至周三调研新增的潜在客户；确保一周内可拨打的潜在客户数量保持在 50+；独立任务（bdr-v3-phone-waterfall-midweek）便于单独安排和监控

运营说明：

• 如果电话瀑布流程耗时超过 8 分钟，则发送 Slack 警报（表示 API 响应缓慢或积压量较大）
• 在仪表板记录成功率（目标是总验证率达到 65%+）
• 如果触发 Apple/Apollo API 速率限制，则将请求加入队列，并采用指数退避策略重试
• 发生错误时：跳过 Clay 丰富处理，仅返回 Apollo 结果（有一些电话号码总比一个都没有好）

## 必需的 MCP 工具

Epiphan CRM（主要数据源）

• hubspot_search_contacts — 提取 phone = null 的潜在客户，并应用 Golden Rules 筛选条件
• hubspot_get_contact — 如有需要，获取完整联系人详情
• crm_search_customers — 在 Epiphan 客户数据库中核查公司（device_count、channel 标记）

Apollo（第 2 阶段：电话号码验证）

• apollo_people_match — 按姓名 + 电子邮件 + 公司查询人员，返回已验证的电话号码
• （无额外费用 — 已包含在 Apollo 计划中）

Clay（第 3 阶段：电话瀑布流程）

• find-and-enrich-contacts-at-company — 按公司 + 职位筛选条件批量丰富联系人
• add-contact-data-points — 添加自定义电话号码数据点以丰富结果
• find-and-enrich-list-of-contacts — 按姓名 + 公司丰富指定联系人
• get-task — 轮询异步丰富处理结果
• （会消耗 Clay 积分 — 请监控支出）

HubSpot API（第 4 阶段：同步）

• hubspot_update_contact（逐个联系人循环；仅可通过直接 REST API 批量处理）— 将已验证的电话号码写回 HubSpot
• 或者按需使用 HubSpot 原生批量导入功能

相关的同级技能与任务

• prospect-research-to-cadence-skill — 潜在客户质量门槛、Golden Rules 筛选条件、ICP 评分
• sales-revenue-skill — ICP 垂直领域定义、意向信号权重
• hubspot-revops-skill — HubSpot 批量操作、联系人筛选模式、负责人 ID 映射
• CLAUDE.md § ATL/BTL Classification v1.0 — ATL/BTL/Gray 分类的已批准职位关键词模式（2026-03-17）

上游与下游计划任务

• bdr-v3-prospect-enrich — 星期一上午 6:00 公司概况刷新（在电话瀑布流程运行前执行）
• bdr-v3-phone-waterfall-midweek — 星期三上午 6:15 周中电话验证运行（新增）
• bdr-v3-prospect-refresh — 星期一上午 6:30 销售进度刷新（在电话瀑布流程运行后执行）

外部依赖

• HubSpot API： 联系人搜索 + 批量更新
• Apollo API： 人员匹配（无额外费用）
• Clay API： 瀑布式丰富处理（需要有效订阅和可用积分）
• Dialpad/Aircall API： 用于直接拨号队列同步的可选集成

预计月度成本

• Apollo： $0（已包含）
• Clay： $150-300，具体取决于补全的联系人数量（监控瀑布流阶段）
• HubSpot： 已在使用
• 可变成本合计： 约 $200-300/月（Clay 积分）

<scheduled_automation>

任务 ID：

• bdr-v3-phone-waterfall（周一上午 6:15 运行）
• bdr-v3-phone-waterfall-midweek（周三上午 6:15 运行）

触发条件： 按用户本地时区，每周一和周三上午 6:15 定期运行

完成时发送 Slack 通知：

✅ Phone Waterfall Complete (Mon 6:15 AM)
   Pulled:       {N} leads
   Verified:     {X+Y} phones ({%})
   HubSpot Sync: ✓
   Queue:        Ready to dial
   Leads/hour:   {rate}

出错时：

⚠️ Phone Waterfall Partial (Mon 6:15 AM)
   Apollo completed ({X%})
   Clay failing — check credits
   Manual action: Continue with Apollo-only queue

</scheduled_automation>

---

参考：黄金规则筛选器

以下为硬性门槛——如果符合任何一项条件，则完全跳过该联系人：

条件	值	操作
lifecyclestage	'customer'	跳过
first_conversion	包含 'Pearl' 或 'setup' 或 'Connect'	跳过
公司 device_count	>= 1	跳过
公司 is_channel	true	跳过
hubspot_owner_id	82625923, 423155215, 190030668	90 天未活跃的例外：如果超过 90 天无活动，则保留（Tim 审核 ATL/BTL 和价值）。如果少于 90 天，则跳过。Ron=全部，Lex/Phil=仅 NA。

</Golden Rules>

---

示例：电话瀑布流实战

完整运行示例（抓取 247 条潜在客户 → 159 条已验证且可拨打，成功率 64.4%，耗时 7 分 30 秒）请参见 reference/waterfall-example.md。

输出结果旁路文件

写入 ~/.claude/skill-analytics/last-outcome-phone-verification-waterfall.json：{"ts":"[UTC ISO8601]","skill":"phone-verification-waterfall","version":"1.0.0","variant":"default","status":"[success|partial|error]","runtime_ms":[ms],"metrics":{"contacts_processed":[n],"apollo_verified":[n],"clay_verified":[n],"total_callable":[n],"verification_rate_pct":[n]},"error":null,"session_id":"[YYYY-MM-DD]"}