Lead Qualification Engine

Qualify leads against custom criteria through a structured intake process, then score lead lists in parallel with confidence ratings and reasoning.

Three Modes of Operation

Mode 1: Full Intake + Qualify

No existing qualification prompt. Run intake to build one, save it, then qualify leads.

Trigger: User provides no qualification prompt file.

Mode 2: Reuse Prompt + Qualify

User references an existing qualification prompt file — skip intake, go straight to scoring.

Trigger: User tags or references a file in skills/lead-qualification/qualification-prompts/.

Mode 3: Refine / Calibrate

User has seen results and wants to adjust criteria. Update the saved prompt, re-run.

Trigger: User says something like "refine", "adjust", "that's wrong", or provides feedback on qualification results.

Phase 1: Intake (Mode 1 Only)

The goal is to build a complete picture of who the user considers qualified vs disqualified. Present questions in bulk rounds so the user can answer efficiently.

Round 1 — Core Questions (Present All at Once)

Present these questions as a numbered list. Tell the user: "Answer what's relevant, skip what's not. I'll follow up on anything I need to clarify."

Product & Campaign Context:

1. What's your product/service in one sentence?
2. What problem does it solve and for whom?
3. What's the specific campaign or outreach angle? (e.g., "targeting companies that just raised Series A", "going after teams switching from Competitor X")

Company-Level Criteria: 4. What company sizes are you targeting? (e.g., 1-10, 11-50, 51-200, 201-1000, 1000+) 5. What industries or verticals are a good fit? 6. Any industries or company types to explicitly EXCLUDE? 7. Geographic targets? Or is this global? 8. Geographic exclusions? 9. Does company stage matter? (e.g., seed, Series A, Series B+, public) 10. Any revenue range or funding range that matters?

Person-Level Criteria: 11. What job titles or roles are your ideal buyers? 12. What titles are explicitly disqualified? 13. Does seniority level matter? (e.g., must be Director+, VP+, C-level) 14. What departments should they be in? (e.g., growth, marketing, sales, engineering) 15. Minimum tenure at current company? (e.g., 6+ months to have buying power) 16. Does total years of experience matter?

Behavioral & Situational Signals: 17. Are there tech stack signals that qualify or disqualify? (e.g., "uses Salesforce" = good fit) 18. Does recent company activity matter? (e.g., hiring spree, funding round, product launch) 19. Are there content/posting signals? (e.g., "posted about AI" = relevant) 20. Any other signals that indicate high intent or good fit?

Dealbreakers & Instant Qualifiers: 21. What are your HARD DISQUALIFIERS — things that instantly make someone a "no" regardless of other factors? 22. What are your STRONGEST QUALIFIERS — things that make someone an almost certain "yes"?

Round 2 — Follow-Up Probes

Based on the user's answers, ask 5-10 targeted follow-ups to resolve ambiguity. Examples:

• "You said mid-market — does that mean 50-500 or 50-1000 employees?"
• "You mentioned VP of Growth — would a 'Head of Growth' also qualify, or only VP title?"
• "You didn't mention geography — should I treat this as global?"
• "For tenure, you said 6 months minimum. What about someone who's 4 months in but was promoted internally?"
• "You mentioned Series A companies. What about bootstrapped companies with equivalent revenue?"

Round 3 — Edge Case Scenarios (Optional but Recommended)

Present 3-5 hypothetical lead profiles that test boundary cases. Ask "Would you qualify this person?"

Example scenarios to construct (adapt based on the user's criteria):

• Someone who fits the title but is at a company that's slightly too large/small
• Someone at the right company but with a borderline title
• Someone who matches on everything but has low tenure
• Someone who doesn't match the title exactly but has high intent signals
• Someone at a competitor's customer

This round catches implicit criteria the user hasn't articulated.

Generate & Save Qualification Prompt

After intake is complete, synthesize all answers into a structured qualification prompt. Save it to:

skills/lead-qualification/qualification-prompts/[campaign-name].md

The saved prompt MUST follow this structure:

# Qualification Prompt: [Campaign Name]

Generated: [date]

## Campaign Context
- **Product:** [one-liner]
- **Campaign Angle:** [specific angle]
- **Problem Solved:** [what and for whom]

## Hard Disqualifiers (Instant No)
- [list each with explanation]

## Hard Qualifiers (Instant Yes)
- [list each with explanation]

## Company Criteria
| Criterion | Qualified | Disqualified | Notes |
|-----------|-----------|--------------|-------|
| Size | [range] | [range] | |
| Industry | [list] | [list] | |
| Geography | [list] | [list] | |
| Stage | [list] | [list] | |
| Funding/Revenue | [range] | [range] | |

## Person Criteria
| Criterion | Qualified | Disqualified | Notes |
|-----------|-----------|--------------|-------|
| Titles | [list] | [list] | |
| Seniority | [level+] | [below level] | |
| Department | [list] | [list] | |
| Tenure | [minimum] | [below minimum] | |
| Experience | [range] | [range] | |

## Behavioral & Situational Signals
- [list signals that boost qualification]
- [list signals that reduce qualification]

## Confidence Rules
- **High Confidence:** Enough data available for company size, title, tenure, and at least one signal.
- **Medium Confidence:** Missing one or two non-critical data points but core criteria are clear.
- **Low Confidence:** Missing critical data points (e.g., no company size, unclear title). Still make a yes/no call but flag it.

## Edge Case Guidance
- [specific guidance derived from Round 3 scenarios]
- [any nuanced rules from the intake conversation]

## Qualification Reasoning Instructions
When evaluating a lead, structure your reasoning as:
1. Check hard disqualifiers first — if any match, immediately disqualify.
2. Check hard qualifiers — if any match, lean strongly toward qualifying.
3. Evaluate company criteria against thresholds.
4. Evaluate person criteria against thresholds.
5. Factor in behavioral/situational signals as tiebreakers.
6. Assign confidence based on data completeness.
7. Write 2-3 sentence reasoning summarizing the decision.

Phase 2: Lead Qualification

Step 1 — Parse Input

Accept any of these input formats:

• CSV file path — Read directly from filesystem (default)
• LinkedIn profile URLs — One or more URLs provided inline
• Inline list — Names/companies listed in the message
• Google Sheet URL — If the user provides a Google Sheet, use whatever Google Sheets tool is available to read it
• Any other source — Ask the user to export as CSV or paste the data

Detect the format automatically based on what the user provides.

Step 1.5 — Batch Enrichment via Apify

When: The input contains a linkedin_url column (or LinkedIn URLs are available). Skip when: No LinkedIn URLs are present, or the user explicitly says to skip enrichment.

Before LLM qualification, batch-enrich all leads to gather structured profile data. This is MUCH faster and cheaper than per-lead web searches during qualification.

Run the enrichment script:

python3 skills/lead-qualification/scripts/enrich_leads.py INPUT_CSV \
  --output ENRICHED_CSV \
  --cache-hours 24

Use --dry-run first to show the cost estimate without calling Apify.

What this does:

1. Reads all LinkedIn URLs from the input CSV
2. Checks local cache (24h default) — skips profiles already enriched
3. Sends uncached URLs to Apify in batches of 50
4. Returns enriched CSV with: enriched_title, enriched_company, enriched_industry, enriched_location, enriched_connections, enriched_education, enriched_experience_years, enriched_headline, `enriched_a