data-enrichment

Data Enrichment

Decorate raw Lead records with verified email statuses, phone numbers (mobile/landline classified), normalized social links, and citable personalization hooks. The output is a Lead record lead-scoring can score with confidence and cold-email can write an opener against without inventing context.

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 enriched lead records (verified emails, phones, personalization hooks, technographics, signals) per the lead schema. 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.

When to Use

• "Verify these 500 emails before we send"
• User has leads with unverified emails, missing phones, or no personalization hooks
• BYO list needs schema repair before scoring
• Stale records need re-verification before outreach
• Pre-scoring quality gate after any sourcing run
• Pre-outreach freshness pass before high-effort sequences

Legend — Enrichment Confidence (per derived field)

• [H] — verified primary source (verifier API "valid", LinkedIn first-party)
• [M] — single secondary source (third-party DB, pattern-guess corroborated by one signal)
• [L] — inferred (pattern guess only, similar-account extrapolation)

Quick Reference

Concept	Value
Three passes	Email verify → Phone discovery → Hook capture
Verifier waterfall	Syntax → MX → SMTP → catch-all → role-based detection
Email status enum	verified / risky / catch-all-domain / role-based / invalid / unverified
Phone status enum	mobile / landline / voip / dnc / unverified / invalid
Hook rule	Permalink + date OR null — no URL, no hook
Catch-all rule	Verifier "valid" + accept-all domain → catch-all-domain (never verified)
Freshness windows	Email: 90d; phone: 12mo; hook: 90d
Compliance	EU → gdpr_basis: legitimate-interest; DNC → strip phone; role-addresses → never Tier-1
Push routing	PATCH person for verified; interaction:research only for [unverified — needs check]

Procedure

1. Triage the input batch. Group records: email-verify-only / phone / hook / all-three / fresh-skip. Surface counts.
2. Cost-quote across passes. Estimate email verify + phone + hook. User chooses passes if budget tight. Reference ${HERMES_SKILL_DIR}/references/enrichment-deep-reference.md for verifier cost models. If an enrichment API is not connected, trigger Clarification Protocol: (A) browser session for manual lookup, (B) CSV upload of pre-enriched records, (C) skip the field and mark [UNVERIFIED]. Honor user choice on first response.
3. Email verification waterfall. Syntax → MX → verifier API → map result to email_status enum. Stamp provenance_email: [verified: <verifier>:run_<id>] for valid; [unverified — needs check] for risky/unknown. Tag confidence [H/M/L] per derived field.
4. Phone discovery + classification. Hunter / Lusha lookup; classify mobile / landline / voip; cross-check DNC for US contacts. Stamp phone_status.
5. Personalization-hook capture. Within permission flags: LinkedIn posts → news search → podcast → company blog → G2 review. Capture source URL + date + verbatim text. Hooks ship with permalink OR null. If you reference any Anti-ICP enrichment template (e.g. from ${HERMES_SKILL_DIR}/references/enrichment-deep-reference.md), label it inline as TEMPLATE — DO NOT TREAT AS DATA. Downstream skills must not read template fields as enriched values. Run ${HERMES_SKILL_DIR}/scripts/normalize_lead.py for field updates. 5a. Manual-mode flow (when API enrichment isn't available). 1) Open the lead's LinkedIn (or company) page in a browser; 2) Manually copy-paste fields into the CSV; 3) Tag provenance as manual and confidence [M] unless ≥2 sources verified (then [H]); 4) Push as usual via the same script chain.
6. Compliance pass. EU/UK → gdpr_basis; personal-email B2B flagged; phone_status: dnc strips phone.
7. Dedup re-check. Newly-discovered LinkedIn URLs / emails may collide with existing CRM. Run ${HERMES_SKILL_DIR}/scripts/dedup_leads.py. Log merges.
8. Push patched records. Run ${HERMES_SKILL_DIR}/scripts/push_to_crm.py. PATCH person fields for verified; interaction:research for unverified.
9. Emit run summary + missing-fields report. One-screen: per-pass results, costs, missing-fields, recommended next skill (lead-scoring).

Pitfalls

• Trusting upstream verifier flags — Apollo's "verified" is hint-quality; always re-verify
• Inventing hooks — "Saw your post on X" with no URL is a hallucinated opener; ship null instead
• Catch-all noise — @apple.com style domains mark everything valid; treat as catch-all-domain
• DNC complacency — TCPA fines are per-violation; strict strip on phone_status: dnc
• Verifying once and forgetting — email lists decay ~30%/year; re-verify quarterly
• Pattern-guessed emails treated as verified — Hunter's pattern-guess is best-guess; verify before promoting

Verification

1. Every patched record's email_status traces to a verifier run_id
2. Every personalization hook has a permalink that resolves
3. Missing-fields report lists which records still need work and why
4. lead-scoring can apply scorecard without [unverified] field gaps capping scores

Output Format

• Sections required: Enriched CSV (same lead schema), Run Summary, Assumptions to Validate
• Tables / fields: Enriched lead schema with email_status, phone_status, personalization_hook, provenance_<field>, confidence [H/M/L] per derived field
• Length target: Run Summary ≤300 words; Assumptions to Validate as bulleted list
• File type: CSV (UTF-8, RFC 4180) + markdown summary
• Mandatory closing sections: Run Summary (records processed, fields filled, confidence distribution, cost), Assumptions to Validate, Recommended Next Skill (lead-scoring)