lead-scorer

Lead Scorer

Scores inbound or scraped leads using a multi-factor algorithm. All weights, thresholds, and bonuses are read from agency.config.json so the scoring adapts to any agency without code changes.

Prerequisites

• agency.config.json exists at the repo root with a scoring section containing: platform_weights, hiring_signals, budget_tiers, recency_bonuses, market_boosts, thresholds
• icp section with primary_keywords, secondary_keywords, intent_keywords, negative_keywords
• Lead data in structured format (JSON object or array)

Phase 0: Intake

1. Read agency.config.json from the project root.
2. Extract:
   • scoring.platform_weights -- map of platform name to base score
   • scoring.hiring_signals -- array of phrases that indicate active hiring/buying
   • scoring.budget_tiers -- array of {min, points} sorted descending by min
   • scoring.recency_bonuses -- map of time window to bonus points (e.g., "24h": 15)
   • scoring.market_boosts -- map of market/country to bonus points
   • scoring.contact_surface_bonus -- bonus points for multi-channel reachability
   • scoring.thresholds -- {hot, warm} cutoffs
   • icp.primary_keywords -- high-relevance service keywords (+10 each match)
   • icp.secondary_keywords -- medium-relevance keywords (+5 each match)
   • icp.intent_keywords -- buying-intent phrases (+10 each match)
   • icp.negative_keywords -- disqualifiers (score = 0, immediately reject)
   • outreach.daily_targets -- { company_leads: 5, gig_leads: 20, total: 25 }
   • outreach.geo_split -- { international_pct: 75, india_pct: 25 }
3. Accept the lead(s) to score. Each lead should have as many of these fields as available:
   • title -- the post/gig/job title or subject line
   • description -- the full text body
   • platform -- where the lead was found
   • budget -- numeric budget amount (if available)
   • currency -- budget currency
   • posted_at -- ISO timestamp or relative time string
   • country -- country of the lead or company
   • url -- source URL
   • lead_type -- "gig" or "company" (from signal-scanner classification)
   • geo_bucket -- "international" or "india" (from signal-scanner)

Phase 1: Negative Keyword Check

For each lead, scan title and description against every entry in icp.negative_keywords (case-insensitive substring match).

• If ANY negative keyword matches: score = 0, tier = REJECTED, skip all remaining phases for this lead.

Phase 1.5: Lead Type Awareness

Apply different scoring standards based on lead_type:

Company Leads (target: 5/day)

• Apply FULL scoring algorithm (all phases below)
• Extremely high quality bar: only HOT leads pass
• Company leads must score >= thresholds.hot to be included

Gig Leads (target: 20/day)

• Apply simplified scoring: platform base + keyword match + budget + recency
• Skip hiring signal bonus (gigs ARE the hiring signal)
• Higher volume: HOT threshold is sufficient
• Must have clear buying signal and budget to qualify

Phase 2: Platform Base Score

Look up lead.platform in scoring.platform_weights.

• If the platform exists in the map: base_score = platform_weights[platform]
• If the platform is not in the map: base_score = 10 (default floor)

Phase 3: Keyword Match Scoring

Combine title + description into a single lowercase text blob. For each keyword list, count distinct keyword matches (not occurrences):

• Primary keywords: For each match, add +10 points. Cap at 3 matches (max +30).
• Secondary keywords: For each match, add +5 points. Cap at 3 matches (max +15).
• Intent keywords: For each match, add +10 points. Cap at 2 matches (max +20).

keyword_score = primary_points + secondary_points + intent_points

Phase 4: Hiring Signal Bonus

Scan the text blob against scoring.hiring_signals (case-insensitive).

• If ANY hiring signal matches: add +20 points (one-time bonus, not per-match).
• Note: For gig leads (lead_type == "gig"), skip this phase. Gigs ARE the hiring signal, so the bonus is already baked into the platform base score.

Phase 5: Budget Tier Scoring

If lead.budget is a number > 0:

• Iterate scoring.budget_tiers from highest min to lowest.
• The first tier where lead.budget >= tier.min gives budget_points = tier.points.
• If no budget data: budget_points = 0.

Phase 6: Recency Bonus

Calculate the age of the lead from lead.posted_at relative to now.

• If age <= 24 hours: add scoring.recency_bonuses["24h"] points
• Else if age <= 48 hours: add scoring.recency_bonuses["48h"] points
• Else if age <= 72 hours: add scoring.recency_bonuses["72h"] points
• Else: 0 points

If posted_at is not available: 0 points.

Phase 7: Market Boost

Look up lead.country in scoring.market_boosts (case-insensitive, also check common abbreviations like "US" for "United States").

• If found: add the boost points.
• If not found: 0 points.

Phase 7.5: Contact Surface Bonus

If the lead includes a contact_surfaces object:

• channel_count >= 3: add scoring.contact_surface_bonus.channels_3_plus points (default 15)
• channel_count == 2: add scoring.contact_surface_bonus.channels_2 points (default 5)
• channel_count <= 1 or missing: 0 points

This bonus rewards leads reachable through multiple channels, enabling the full multi-channel outreach cadence.

Phase 8: Final Score and Tier Assignment

total_score = base_score + keyword_score + hiring_bonus + budget_points + recency_bonus + market_boost + surface_bonus

Assign tier using scoring.thresholds:

• total_score >= thresholds.hot => HOT
• total_score >= thresholds.warm => WARM
• total_score < thresholds.warm => COOL

Phase 8.5: Geo Split Enforcement

After scoring all leads, enforce the 75/25 geo split from config:

1. Separate scored leads into two pools: international and india
2. Target: ~75% international (~19 of 25 leads), ~25% India (~6 of 25 leads)
3. Within each pool, rank by score descending
4. Select top N from each pool to hit the target split
5. If one pool is short, allow the other pool to fill remaining slots

For company leads specifically (5/day target):

• ~4 international, ~1 India

For gig leads (20/day target):

• ~15 international, ~5 India

Flag any lead that was excluded due to geo split enforcement: "excluded_reason": "geo_split_cap_reached"

Phase 9: Output

Return a JSON array of scored leads:

[
  {
    "url": "https://...",
    "platform": "Freelancer",
    "title": "Need Shopify developer for store redesign",
    "score": 75,
    "tier": "HOT",
    "lead_type": "gig",
    "geo_bucket": "international",
    "breakdown": {
      "platform_base": 45,
      "keyword_matches": {
        "primary": ["shopify developer", "shopify redesign"],
        "secondary": ["ecommerce redesign"],
        "intent": ["need a developer"]
      },
      "keyword_score": 30,
      "hiring_signal": true,
      "hiring_bonus": 20,
      "budget_points": 0,
      "recency_bonus": 0,
      "market_boost": 0,
      "surface_bonus": 15,
      "channel_count": 4
    },
    "reject_reason": null
  }
]

For rejected leads, include "reject_reason": "Matched negative keyword: 'i am a shopify developer'" and "tier": "REJECTED".

Phase 10: Log

If the CRM is configured, write scored leads to the CRM using the crm-writer skill. Log: url, platform, title, score, tier, lead_type, geo_bucket, scored_at timestamp.

Summary format:

Scored {N} leads:
- HOT: {count}, WARM: {count}, COOL: {count}, REJECTED: {count}
Geo split: X% international, Y% India (target: 75/25)
Lead mix: N company leads, N gig leads (target: 5/20)

Example Usage

Trigger phrases:

• "Score these leads"
• "Qualify this lead list"
• "Run lead scoring on these results"
• "Which of these leads are hot?"

User: Score these leads from today's signal scan
Assistant: [reads agency.config.json, applies scoring algorithm with lead type awareness and geo split enforcement, returns sorted JSON with HOT leads first]