/list-builder

name: list-builder
description: META skill — build the largest possible qualified lead list for any request, end to end. Orchestrates discovery (Prospeo + GetLeads + Blitz + Google Maps + lookalike snowball from /list-expander), AI qualification with live-website verify, uncapped contact pull (GetLeads → Blitz → Prospeo), and provider emails (GetLeads/Blitz/Prospeo) validated with MillionVerifier before sending. Use for any "build me a list", "get me leads for X", "find everyone who...", client list request, or campaign list build. Starts with a 7-line intake brief; outputs to Postgres, Google Sheet, and/or CSV (asks which).

List Builder — the meta list-building process

⚡ OPERATE VIA THE RUNBOOK

The manual phase-by-phase flow below still documents the concepts, but the OPERATIONAL path is now three one-command scripts — see **RUNBOOK.md in this skill directory** for the decision table and failure playbook. In short:

npx tsx scripts/make-judge.ts --spec=judge-spec.json --out=prompt.txt   # judge (mandatory blocks)
npx tsx scripts/run-lane.ts  --config=lane.json                         # full lane, resumable
npx tsx scripts/snowball.ts  --config=lane.json                         # sweep until dry
npx tsx scripts/contacts.ts  --config=lane.json                         # contacts + emails after approval

Re-running the same command resumes after ANY failure. `summary.md` line 1 = READY / NOT READY with the next command. Cross-run dedup via the OPTIONAL `list_builder_judged_domains` Postgres registry (WAL-first; `scripts/registry.ts`; DDL in `references/registry-schema.sql`; leave `LIST_REGISTRY_DB_URL` unset and it degrades to per-run WAL dedup). Prospeo pacing is globally rate-limited across processes (lib.ts slot reservation — never tune it).

One entry point for every list request. This skill owns the PROCESS and delegates to tool skills that own the provider gotchas. Read the referenced skill whenever you touch its provider.

| Layer | Delegate | |---|---| | Company discovery + qualification + snowball | `/list-expander` (scripts in its `scripts/`) | | Prospeo filters/syntax | `/prospeo-search-api` | | Blitz domain→people | `/blitz-list-builder` (`scripts/find-contacts.ts`) | | GetLeads counts/exports | `scripts/getleads-client.ts` (counts are free) — optional, skipped without a key | | Email validation | provider emails from GetLeads/Blitz/Prospeo → `leads-final.csv`; validate with MillionVerifier (`/cold-email-starter-kit`) before upload | | Judge tuning | `/icp-prompt-builder` | | Local/SMB discovery | `/google-maps-list-builder` | | List QA before delivery | `/list-quality-scorecard` |

Scripts in THIS skill's `scripts/`: `contacts-merge.ts` (normalize/dedup contact pulls, keeps every raw provider field), `enrich-domains.ts` (batch Prospeo enrichment for any domain list — headcount/revenue/state/ phone; strips subdomains), `classify-batch.ts` (multi-segment nano classifier — one pass assigns each company to one of N segments; use for industry sweeps that feed several lanes).

**Observability + multi-lane helpers (2026-07-14):**

• `fleet.ts` — read-only status board over `~/output/list-builder/lanes/*`: one row per lane

(current stage, status, rows in newest stream, minutes idle, snowball in flight, READY?). Zero side effects — safe to run against live runs. `npx tsx scripts/fleet.ts` (add `--json`).

• `multi-lane-classify.ts` — when several lanes for one client draw from OVERLAPPING pulls,

union their MERGE candidate pools by domain and label every unique company in ONE nano pass (labels = lane names, prompt built from each lane's judge ICP one-liner). Writes per-lane `<client>-<lane>-candidates.csv` for consumption via `extra_candidates`. Additive — does not change run-lane's per-lane flow. `npx tsx scripts/multi-lane-classify.ts --lanes=a.json,b.json`.

Requirements / env

**Prerequisites:** Node ≥ 18 with `npx tsx` (`npm i -g tsx`); `python3` + `pip install gspread` only if you use the Google Sheet destination; `psql` on PATH only if you set `LIST_REGISTRY_DB_URL`. Copy the repo-root `.env.example` to `.env` and fill in the keys below — scripts walk up from `skills/list-builder/scripts/` to find it.

Put these in a `.env` at the repo root (or `~/.env` — `loadEnv()` reads both) or export them.

**REQUIRED**

| Var | What for | Get one | |---|---|---| | `PROSPEO_API_KEY` | company + people search, the primary discovery source | sign up at https://prospeo.io | | `OPENAI_API_KEY` | the GPT-5-nano judge that scores every candidate | sign up at https://platform.openai.com |

**OPTIONAL** — each of these degrades gracefully: the script logs a skip line and continues.

| Var | What for | Without it | |---|---|---| | `OPENAI_API_KEY_NANO` | a separate key/project for nano scoring | falls back to `OPENAI_API_KEY` | | `OPENAI_ICP_MODEL` | override the judge model (default `gpt-5-nano`) | uses the default | | `GETLEADS_API_KEY` | free contact counts + exports, first stop in Phase 4 (sign up at https://getleads.io) | contacts.ts marks GETLEADS `skipped` and every domain falls through to Blitz/Prospeo | | `BLITZ_API_KEY` | domain→people fallback via `/blitz-list-builder` (see that skill for signup) | BLITZ stage skips, Prospeo covers those domains | | `EXA_API_KEY`, `PARALLEL_AI_API_KEY` | lookalike / entity discovery inside `/list-expander` Phase 2 (sign up at https://exa.ai, https://parallel.ai) | those sub-sources are skipped, seeds + filters still run | | `LIST_REGISTRY_DB_URL` | Postgres URL for cross-run dedup (DDL: `references/registry-schema.sql`) | WAL-only dedup: a run never re-judges itself, but earlier runs are not deduped | | `MILLIONVERIFIER_API_KEY` | validate `leads-final.csv` before upload (https://millionverifier.com) | OPTIONAL for the build; REQUIRED before you send | | `GOOGLE_APPLICATION_CREDENTIALS` | service-account JSON for the Google Sheet destination (`push-sheet.py`) | omit `destination.sheet_id` in lane.json for a CSV-only