lead-sourcing-clay

Lead Sourcing — Clay

Use Clay's table-based orchestration to combine multiple data providers (Apollo for firmographic search, Hunter for emails, BuiltWith for tech, MillionVerifier for deliverability) in a single workflow. Output: normalized, multi-source-provenance-tagged Lead records — same schema as lead-sourcing-apollo but with enrichment baked in.

Clarification Protocol

When you encounter any of the following, STOP and ask the user — do NOT make a silent assumption, and do NOT flatly refuse:

• Ambiguous or missing input
• A fork in approach (multiple valid frameworks, segments, scopes, or sources)
• A rule that would block progress
• An assumption that materially shapes the output
• Unverified data that a downstream step depends on

Present 2–4 concrete options with trade-offs and your recommendation.

Format:

Decision needed: <what's being decided> Options:

• A) <option> — trade-off
• B) <option> — trade-off
• C) <option> — trade-off My recommendation: <X> because <reason>. Confirm or pick a different option before I continue.

Refusing to proceed is NEVER the final answer. Every "block" must come with an override option. If the user picks an override, honor it on the first request — do not re-prompt the same block multiple times in one run.

Scope

This skill ONLY produces Clay-orchestrated lead CSV records (multi-source enriched). Do not expand into adjacent topics. If the user's request implies adjacent scope, trigger Clarification Protocol with options to (A) stay in scope, (B) note the adjacent need as a follow-up, (C) hand off to a different skill.

Verification Requirements (Derived Details Only)

The search action itself does NOT require web verification — Clay multi-source returns are first-party for sourcing. However, every derived person/company detail that this skill or downstream skills will state as fact (titles, seniorities, company size, technographics, funding) MUST be verified or marked [UNVERIFIED] before push.

• Tag derived details inline as [H/M/L][Sn].
• Source URL goes in the lead record's provenance field.
• Unverified derived details belong in ## Assumptions to Validate, NOT in the lead's main fields.

Sources are mandatory for derived claims. If you cannot cite a source, mark [UNVERIFIED].

When to Use

• User has Clay and wants Apollo + email-finder + tech-stack + verifier in one pull
• "Build me a Clay table for our ICP"
• Single-source skill misses fields Clay can fill in-flow
• User has an existing Clay table CSV to push to CRM
• Multi-source orchestration when the cost model favors Clay over direct-API

Legend — Confidence Score (Derived Fields)

• [H] High — verified by ≥2 independent primary sources within last 6 months
• [M] Medium — single primary source, OR multiple secondary sources agree
• [L] Low — inferred / single secondary source / older than 12 months

Quick Reference

Concept	Value
Modes	API (key set) / Manual (Clay seat, output spec) / BYO (table CSV)
Default chain	Apollo (search) → Hunter (email) → BuiltWith (tech) → MillionVerifier (verifier)
Per-row cost	Scales linearly per row × per column; always quote per-provider before pull
Free re-run window	~24h on same row × column (Clay caching)
Provenance	Each Clay column emits its own provenance per row — flatten only at push time
Source priority (overlapping fields)	Verifier-checked > Hunter pattern guess > Apollo claim
Replay handle	clay_table_id — preserve in run record for 30-day refresh

Procedure

1. Confirm ICP grounding. Read ICP scorecard from icp-definition. If absent → flag ungrounded, confidence: low.
2. Determine mode. CLAY_API_KEY set → API. Else seat → manual (output spec). Else CSV → BYO. Else → spec-only output.
3. Choose provider chain. Default: Apollo + Hunter + BuiltWith + MillionVerifier. Adjust per ICP — funding-trigger needs Crunchbase, mobile needs Lusha. Reference ${HERMES_SKILL_DIR}/references/ for chain options and cost models.
4. Translate ICP → Clay table spec. Specify search-step filters, enrichment columns, verifier column, output column-set matching Lead schema. Store as reproducible clay_table_spec.
5. Pre-flight: discover(). API mode: dry_run: true preview. Manual: user reports UI count. Surface combined cost broken down by provider. Default behavior: wait for explicit authorization. If the user requests skipping the quote step, trigger Clarification Protocol with options: (A) run dry_run then confirm (default safe), (B) skip dry_run and materialize within cost cap (flag run as confidence: low — quote-skipped), (C) raise cap then re-quote. Honor user override on first request; do not re-prompt. 5a. Search-criteria width gate (Clarification Protocol). If candidate count is far above or below the user's apparent intent, STOP and present options: (A) widen filters (warn: higher row × column volume + per-provider cost compounds), (B) narrow filters (warn: reduced reach), (C) keep current. Recommend based on count vs. ICP target. Honor pick on first response.
6. Materialize the table. Run table (API) or wait for user (manual). Capture clay_table_id. Respect rate limits (~100 rows/sec, backoff on 429).
7. Normalize to Lead schema. Map columns → Lead fields. Each column has own provenance: [verified: clay-apollo:run_<id>], [verified: clay-hunter:run_<id>], etc. Run ${HERMES_SKILL_DIR}/scripts/normalize_lead.py.
8. Dedup against CRM. linkedin_url > email > phone for person; company_domain for company. Run ${HERMES_SKILL_DIR}/scripts/dedup_leads.py. Log merges.
9. Compliance + push + summary. Apply compliance filters. Run ${HERMES_SKILL_DIR}/scripts/push_to_crm.py. Run summary with per-provider cost breakdown. Typically recommends lead-scoring directly (Clay replaces separate enrichment for verified emails).

Pitfalls

• Adding columns without quoting — per-column cost compounds; always re-quote on chain change
• Skipping the verifier column — saving $0.0015/row to ship email_status: unverified is false economy
• Letting Clay handle CRM writeback — breaks source-tag and provenance contract; skill maintains push
• Multi-source provenance collapse — each column has its own provenance; flatten incorrectly and audit value is lost
• Inventing rows when a provider returns nulls — coverage gaps are signal, not failure
• Provider outage handling — blank rows go to review queue, never silently fill them

Verification

1. clay_table_id resolves to the same table on replay
2. Every Lead field carries its column-specific provenance
3. Per-provider costs sum to total ± rounding
4. lead-scoring can consume records without re-enrichment for typical ICPs
5. [unverified] records landed in review queue

Output Format

• Sections required: Lead CSV (per schema), Run Summary (counts, dedup stats, source query, per-provider cost breakdown), Assumptions to Validate
• Tables / fields: see references/csv-schema.md for the canonical Lead CSV column list and encoding
• Length target: depends on query scope (cost-capped per gtm.sourcing_run_record_cap); Run Summary ≤300 words by default
• File type: CSV (lead records) + markdown (run summary)
• Mandatory closing sections: Verification Notes, Assumptions to Validate, Next Step