@vruum/skills 0.4.7 → 0.4.9

package/README.md

@@ -41,7 +41,10 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/engagement-triage` — Review and approve your pending LinkedIn engagement drafts and demand-gen content posts. Use when: triage engagements, review engagement queue, review warming comments, review nurture reactions, review marketing comments, review content drafts, check engagement queue.
 - `/enrich-prospect` — Deep prospect diarization — synthesize everything known about a person into a structured intelligence profile. Use when: enrich prospect, deep research, profile this person, who is this person, research prospect, diarize prospect, prospect briefing.
 - `/outreach-triage` — Review and approve your pending outreach drafts across LinkedIn and email. Use when: triage, review queue, morning review, check messages, approve outreach, what needs review.
-- `/pipeline-fill` — Fill your outreach pipeline by importing new Sales Navigator prospects. Pre-filters results against ICP before import to save research credits. Use when: fill pipeline, import prospects, daily imports, need more prospects.
+- `/pipeline-fill` — Source-agnostic pipeline orchestrator. Picks a source per segment (Sales Nav / YC / CSV / discovery), runs harness deep research, applies a pre-filter gate, then saves into the segment via the backend authoritative match_score>=70 gate. Use when: fill pipeline, import prospects, daily imports, need more prospects, discover prospects from scratch, deep research before import.
+- `/sales-nav-deep-fill` — Sales Nav harness source for /pipeline-fill. Pre-filters Sales Nav profiles via vruum-pipeline-filter, produces a candidate list, hands off to /pipeline-fill for deep research and import. Use when: sales nav with deep research, sales nav harness mode, in-chat sales nav.
+- `/yc-pipeline-fill` — YC harness source for /pipeline-fill. Scrapes YC's public Algolia index, extracts founder LinkedIn URLs, dedups, hands a candidate list to /pipeline-fill for deep research and import. Use when: YC pipeline fill, source from YC, fill segment with YC founders, sales nav dried up, source YC.
+- `/csv-pipeline-fill` — CSV harness source for /pipeline-fill. Reads a CSV, auto-detects headers, maps columns, hands off to /pipeline-fill for harness deep research and import. Use when: import CSV, paste a CSV, csv import, prospect list from CSV, csv harness mode.
 - `/segment-doctor` — Diagnose and fix struggling outreach segments. Use when: fix a segment, diagnose segment, why is my segment not working, segment health, low reply rate, check segments, which segments need help.
 - `/vruum-skills-upgrade` — Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE.
 <!-- generated:skills-end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "e80f9da6dae9eddc25e0dd9c3fef27fcf04c55a903599a90c464266599e7242d"
+  "contentHash": "fe89953973a2a52b8a68248751cb90fa8beb8d71fa74c6b0c365798e78d154b5"
 }

package/skills/csv-pipeline-fill/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: csv-pipeline-fill
+description: >-
+  CSV harness source for /pipeline-fill. Reads a CSV, auto-detects headers, maps
+  columns, hands off to /pipeline-fill for harness deep research and import. Use
+  when: import CSV, paste a CSV, csv import, prospect list from CSV, csv harness
+  mode.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to this repo). Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention the available upgrade in one line and offer `/vruum-upgrade`. Then continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, then continue.
+- Empty → proceed silently.
+
+Never block skill execution on this check.
+
+# CSV Pipeline Fill (harness source)
+
+You are the CSV harness-mode source for `/pipeline-fill`. You read a CSV the operator provides (Apollo export, ZoomInfo, hand-built spreadsheet, LinkedIn export — anything), normalize columns to the canonical candidate-list shape, and hand off to the orchestrator.
+
+**This is the harness counterpart to `/csv-platform-fill`.** The platform skill calls `start_csv_import` and lets backend agents do everything. This skill stops at producing a candidate list — Phase A and Phase B run in your chat session (your harness compute), and `save_discovered_person` is called only after the harness pre-filter gate passes.
+
+## Inputs
+
+- `file_path`: absolute path to the CSV. If not provided, ask for it. Common locations: `~/Downloads/`, `.context/attachments/` in the workspace.
+- `segment`: target segment (single)
+- `column_mapping` (optional): explicit `{header_name: canonical_field}` mapping if headers don't auto-resolve. Default: auto-detect.
+
+## Workflow
+
+### Step 1: Read the file
+
+Use the `Read` tool on the absolute path. If the file doesn't exist, surface a clear error: "File not found at `{path}`. If it's in your Downloads folder, the path is typically `/Users/<you>/Downloads/<file>.csv`." Don't guess.
+
+### Step 2: Detect delimiter + encoding
+
+- **Delimiter:** read the first line. If it has more `;` than `,`, use `;`. If more tabs than commas, use `\t`. Default: `,`.
+- **Encoding:** assume UTF-8. If decoding fails, fall back to Latin-1 and note the encoding in the report.
+- **BOM:** if the first 3 bytes are `\xef\xbb\xbf` (UTF-8 BOM), strip them before parsing.
+- **Header row offset:** if the first row has only one non-empty cell (likely a title or disclaimer), skip it and treat row 2 as headers.
+
+### Step 3: Detect headers + map columns
+
+The first non-empty data row after the header offset is treated as the header. Lowercase + strip whitespace from each header. Match against canonical fields:
+
+- `name` ← `full_name`, `name`, `contact name`, `prospect`, `contact`
+- `first_name` ← `first_name`, `first name`, `firstname`, `given name`
+- `last_name` ← `last_name`, `last name`, `lastname`, `surname`, `family name`
+- `company` ← `company`, `company name`, `account`, `organization`, `org`, `employer`
+- `linkedin_url` ← `linkedin`, `linkedin url`, `linkedin_url`, `profile`, `linkedin profile`, `linkedin_profile`, `li_url`
+- `email` ← `email`, `email_address`, `work_email`, `business email`
+- `title` ← `title`, `job_title`, `position`, `role`
+
+If `name` is mapped, defer the first/last split to the engine doc's Step 7 (canonical heuristic). If `first_name` + `last_name` are both mapped, use them directly.
+
+### Step 4: Resolve ambiguous mappings
+
+If any required field can't be auto-mapped (`name`/(first+last) AND `company`, OR `linkedin_url`), show the operator the detected headers + sample row and ask which column maps to which field. Don't guess silently — silent guessing is the source of "why did my CSV import 50 prospects with the wrong company" bugs.
+
+For multi-column ambiguity (e.g. two columns matching `email`), pick the leftmost match and note it in the operator output.
+
+### Step 5: Normalize each row
+
+Per row:
+- Strip whitespace from all fields.
+- Lowercase emails.
+- Validate `linkedin_url` matches `^https?://(www\.)?linkedin\.com/in/[^/?]+/?(\?.*)?$`. If invalid (e.g. `https://linkedin.com/company/...`), set to null and log.
+- Strip query strings from LinkedIn URLs (`?utm_source=...` etc.) — canonicalize to `https://linkedin.com/in/<slug>/`.
+- **Skip rows** where neither `linkedin_url` nor (`name` AND `company`) is present. Log the skipped count.
+- **In-CSV dedup**: dedup the candidate list by lowercased `linkedin_url` (preferred), else by `<lowercased name> + <lowercased company>`. Log duplicates dropped.
+
+### Step 6: Pre-filter on size
+
+If the CSV has >200 rows after normalize+dedup, ask the operator: "CSV has {N} rows after dedup. Process all, or first M? (a/N)". Big CSVs eat real time + LinkedIn API quota in the deep-research stage.
+
+### Step 7: Build candidate list
+
+Convert each row to the canonical shape (defined in `pipeline-fill/RESEARCH-ENGINE.md`):
+
+```
+{
+  full_name: <name field if mapped, else null>,
+  first_name: <first_name field if mapped, else null>,
+  last_name: <last_name field if mapped, else null>,
+  company: <company>,
+  linkedin_url: <canonicalized URL or null>,
+  email: <email or null>,
+  person_id: null,
+  title: <title or null>,
+  raw_signals: {
+    source: "csv",
+    csv_path: "<file_path>",
+    csv_row_number: <row index, 1-based>,
+    csv_extra_columns: { <header>: <value>, ... }  // any unmapped columns, preserved for ops
+  }
+}
+```
+
+The `csv_extra_columns` field keeps unmapped data on the candidate so an operator can later inspect it via `get_user_people` if a question comes up about why a particular prospect was imported.
+
+### Step 8: Hand off to /pipeline-fill (canonical handoff prompt)
+
+Emit the canonical handoff prompt (defined in `pipeline-fill/RESEARCH-ENGINE.md`):
+
+```
+Candidate list ready: {N} prospects from csv (after {dedup_count} dedup).
+
+NEXT: invoke /pipeline-fill Step 3 onward (deep research → harness gate → save) with this list and segment {segment_id}.
+
+Continue automatically? (y/n)
+```
+
+- Operator answers `y` → continue into the engine doc's Step 3.
+- Operator answers `n` → exit cleanly with the candidate list visible in chat.
+
+## Edge cases
+
+- **Tabs/semicolons** as delimiter — auto-detected from first line.
+- **BOM/encoding** — UTF-8 BOM stripped; Latin-1 fallback if UTF-8 fails.
+- **Headers in row 2** — auto-detected when row 1 has only one non-empty cell.
+- **Duplicate rows** — in-CSV dedup before handoff.
+- **LinkedIn URLs with tracking params** — query string stripped during canonicalization.
+- **Mixed name format** (some rows have full_name, others have first/last) — engine handles both via Step 7's identity-resolution flow.
+- **Empty CSV** — orchestrator says "CSV has no data rows after dedup; nothing to research" and exits.
+
+## Notes
+
+- **Sourcing phase is ~free** (file read + parsing). Real-money costs live in `/pipeline-fill`'s deep-research subagents.
+- **For backend-driven CSV import** (fire-and-forget, no in-chat research): the platform-mode CSV skill calls `start_csv_import` directly and lets backend agents do sourcing/research/gate. Pick this skill when you want to see the deep research happen in your chat instead.
+- **Composability** with `/pipeline-fill`: standard pattern. Run this skill standalone for "I just want this CSV imported with deep research today" or invoke via the orchestrator's source picker.

package/skills/pipeline-fill/RESEARCH-ENGINE.md

@@ -0,0 +1,288 @@
+# Pipeline Fill — Research Engine
+
+This is the canonical research-engine doc referenced by `/pipeline-fill` (orchestrator) and all harness-mode source skills (`/sales-nav-deep-fill`, `/yc-pipeline-fill`, `/csv-pipeline-fill`, plus inline manual-list mode).
+
+When a source skill produces a candidate list, it hands off to this engine via the canonical handoff prompt at the bottom of this doc. The engine then runs Steps 3–8: pre-flight → Phase A → Phase B → harness gate → save → report.
+
+The orchestrator's SKILL.md owns the front-of-flow: segment picker (Step 1), source picker (Step 2), and the inline manual-list parser. Everything from Step 3 onward is defined here. **Don't duplicate this doc in source skills** — link to it.
+
+---
+
+## Candidate List Shape (canonical, single source of truth — load-bearing)
+
+All harness source skills produce candidate lists matching this shape exactly. The orchestrator consumes only this shape. Adding a field requires updating this section, then auditing each source skill.
+
+```
+[
+  {
+    full_name: string | null,        // "Jane Smith" — convenience; engine splits to first/last in Step 7
+    first_name: string | null,       // optional if full_name set; one of these MUST be present
+    last_name: string | null,         // optional if full_name set
+    company: string | null,           // "Acme Co" — null OK if linkedin_url is set
+    linkedin_url: string | null,      // canonical /in/ URL — null OK if name+company set
+    email: string | null,             // null = pending lookup; engine doesn't gate on email presence
+    person_id: string | null,         // pre-existing Vruum person UUID; null for new (resolved in Step 7)
+    title: string | null,             // optional, fills via Phase B if missing
+    raw_signals: object | null        // source-specific opaque blob (yc batch, csv row#, etc.)
+  }
+]
+```
+
+**Rules:**
+- At minimum, each candidate needs **either** `linkedin_url` **or** (`name`-fields + `company`). Candidates with neither are skipped at Step 3.
+- `full_name` is a convenience for sources that don't pre-split. Engine's Step 7 splits via last-space heuristic (`Jane van der Merwe` → first=`Jane`, last=`van der Merwe`). Multi-token surnames like `Maria Del Carmen Garcia` may split imperfectly — Phase B's `fetch_linkedin_data` returns canonical first/last when `linkedin_url` is present and overrides the heuristic.
+- Field additions are additive only. Removing a field is a breaking change for source skills.
+
+---
+
+## MCP-availability precheck (load-bearing — runs before Step 3)
+
+Before any other Step 3 work, call `get_research_playbook(segment_id=<id>)`. If this fails with "tool not found" / 404 / connection error, abort the run with this exact message:
+
+> Vruum MCP not configured as a user-scoped server. Run:
+>
+> `claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp`
+>
+> and retry. (The cloud `claude.ai Vruum` connector doesn't propagate to subagents — they need `vruum` configured at the user scope in `~/.claude.json`.)
+
+This catches the common silent-failure mode: deep-research subagents dispatch, all return `STATUS: failed` because they can't reach MCP, and the operator gets a confusing "0 enrolled, no errors" report. One MCP call upfront vs an hour of debugging.
+
+The `get_research_playbook` call also doubles as the ICP load — capture target_titles, target_industries, value_proposition, positioning_angle, ACV floor, signals_to_watch, exclusions for use in subagent dispatch prompts.
+
+---
+
+## Step 3 — Pre-flight
+
+Per segment's candidate list:
+
+1. **MCP precheck + ICP load** (above) — abort run on failure.
+2. **Batch dedup against existing pipeline.** Call `batch_search_existing_people(queries=[{name, company, linkedin_url} for each candidate])`. Returns one match record per candidate (in input order). Drop candidates with non-null `match` — they're already in pipeline.
+3. **Batch company-cache check.** Collect unique company domains from surviving candidates. Call `batch_get_company_research(domains=[...])`. Returns `[{domain, cached_research, age_days}]`.
+   - Cache hit (`cached_research != null` AND `age_days <= 90`) → company skips Phase A; the cached research carries forward.
+   - Cache miss or stale (`age_days > 90`) → company joins the Phase A research queue.
+4. **Operator confirmation gate (CSV / large lists only).** If the original candidate list was >200 (CSV) or >100 (manual list), confirm count to process before continuing.
+
+**Latency:** ~2s for batch dedup + ~1s for batch company cache, regardless of list size. (Per-prospect iteration was ~12s for 60 prospects pre-batch primitives.)
+
+---
+
+## Step 4 — Phase A: company research
+
+**Concurrency cap: 10 parallel.** Phase A subagents don't call `fetch_linkedin_data` — they hit `get_company_research`, `fetch_company_website`, `WebFetch`, `WebSearch`. No Unipile rate-limit pressure.
+
+Dispatch one `vruum-company-deep-researcher` per unique uncached company. Subagent file at `.claude/agents/vruum-company-deep-researcher.md` defines the workflow + tools.
+
+Dispatch prompt template (fill in placeholders):
+
+```
+You are vruum-company-deep-researcher. Research this company against segment "{segment_name}".
+
+company_name: {name}
+domain: {domain}
+segment_icp_summary: {one paragraph from get_research_playbook}
+acv_floor: {dollars or default $10K}
+
+Run your workflow (a–i) and return the structured output block.
+```
+
+Each subagent returns: `company_id`, `funding_data`, `growth_metrics`, `current_priorities`, `outbound_motion_score` (0/1/2), `acv_class` (smb/mid/ent), `sales_cycle_inference` (short/medium/long), `triggers[]`, `STATUS: ok | failed`, `CACHE_HIT`.
+
+**Wait for the wave to complete before Phase B.** Phase B inputs depend on Phase A's signals (or null if failed).
+
+**Subagent timeout cascade (load-bearing):** when STATUS=failed for a company, the orchestrator does NOT skip the prospects from that company. Phase B still runs for them with `null` company signals. The harness pre-filter gate then tags them `harness_gate_status: gate_inconclusive` (a fourth status alongside pass/warming/low_priority/dismiss). `save_discovered_person` is still called — the backend's `MatchAnalysisAgent` may have cached company research from earlier runs and gates them appropriately. Surface gate-inconclusive prospects in the final report so the operator can re-run the failed companies later.
+
+**Inter-wave progress line.** After each wave (5–10 subagents):
+```
+[PROGRESS] Phase A: {done}/{total} companies researched, {failed} failed, elapsed {M}m, eta {N}m
+```
+Helps operators distinguish "still working" from "stuck."
+
+---
+
+## Step 5 — Phase B: prospect research
+
+**Concurrency cap: 5 parallel** (lowered from Phase A's 10 because Phase B subagents call `fetch_linkedin_data` and the Unipile rate limiter throws over cap — see `backend/app/domains/channels/services/unipile/rate_limiter.py:36`. Lower concurrency keeps us under the per-account window.)
+
+Dispatch one `vruum-prospect-deep-researcher` per surviving candidate. Subagent file at `.claude/agents/vruum-prospect-deep-researcher.md`.
+
+Dispatch prompt template:
+
+```
+You are vruum-prospect-deep-researcher. Research this prospect against segment "{segment_name}".
+
+full_name: {name}
+first_name: {first_name or null}
+last_name: {last_name or null}
+company: {company}
+linkedin_url: {url or null}
+email: {email or null}
+
+phase_a_signals:
+  acv_class: {smb|mid|ent or null if Phase A failed}
+  outbound_motion_score: {0|1|2 or null}
+  triggers: [list or null]
+
+segment_icp_summary: {one paragraph from get_research_playbook}
+acv_floor: {dollars}
+
+Run your workflow (a–k) and return the structured output block. Note: do NOT call save_discovered_person or start_outreach — those are orchestrator-only and not in your tools list.
+```
+
+Each subagent returns: `topics_of_interest`, `recent_posts`, `opening_hooks[]` (2–3, with source URLs), `decision_maker_level` (junior/mid/senior), `email_status` (found/pending), `role_start_date`, per-prospect `triggers[]`, `STATUS`. Note: `person_id` is NOT returned here — identity resolution happens in Step 7.
+
+**Inter-wave progress line:**
+```
+[PROGRESS] Phase B: {done}/{total} prospects researched, {dismissed_for_linkedin_unavailable} skipped, elapsed {M}m, eta {N}m
+```
+
+---
+
+## Step 6 — Harness pre-filter gate (orchestrator-side, pre-save)
+
+This is a **coarse pre-filter** — its job is to avoid wasted backend `save_discovered_person` calls on obvious dismisses. The **authoritative** gate is server-side `MatchAnalysisAgent.match_score >= 70` and runs inside `save_discovered_person`. The harness gate cannot override the backend gate; it can only dismiss before reaching it.
+
+Per surviving prospect, evaluate four criteria using the segment's playbook ICP and the Phase A + Phase B signals:
+
+### 1. ACV class meets segment threshold?
+- `acv_class >= acv_floor_class` → pass this criterion (smb=$5K, mid=$5–50K, ent=$50K+; segment's `acv_floor` from playbook maps to a class)
+- If no → dismiss `acv_too_low`. Don't call `save_discovered_person`.
+
+### 2. Outbound motion or hiring signal?
+- `outbound_motion_score > 0` OR explicit hiring trigger present → pass
+- If no → flag `warming_candidate` (still call `save_discovered_person` — operator may want to warm-track them; backend match analysis tells us if the segment fit is real)
+
+### 3. Decision-maker level senior?
+- `decision_maker_level == senior` → pass
+- If `mid` → pass with a note (segment owner decides if mid is acceptable)
+- If `junior` → look for a more-senior person at the same `company_id` in the Phase B output set. If found, swap and rerun. If not, dismiss `decision_maker_junior`.
+
+### 4. Trigger event in last 90d?
+- 1+ trigger from Phase A (`funding`, `exec_hire`, `launch`, `m_and_a`, `partnership`) OR Phase B (`new_role`, `topical_post`, `press_mention`, `promotion`) → pass
+- If no → flag `low_priority` (still call `save_discovered_person`)
+
+### Tag each prospect:
+- `harness_gate_status: pass` — all four criteria passed
+- `harness_gate_status: warming` — failed criterion 2 (no outbound motion)
+- `harness_gate_status: low_priority` — failed criterion 4 (no recent trigger)
+- `harness_gate_status: gate_inconclusive` — Phase A failed for this prospect's company (degraded mode)
+- `harness_gate_status: dismiss` — failed criterion 1 (acv) or 3 (junior, no senior swap available); skip backend call entirely
+
+For non-dismiss outcomes, also set `dismiss_reason` to null and `flag` to the relevant reason (warming|low_priority|gate_inconclusive|null).
+
+**The gate is declarative prose — not a hardcoded function.** The orchestrator follows the rules above and tags each candidate. If a future criterion changes, edit this section.
+
+---
+
+## Step 7 — Save chain (everyone except harness-gate dismisses)
+
+Per surviving prospect:
+
+### a. Save company research (once per company)
+If the prospect's company isn't already cached and Phase A produced fresh research, call `save_company_research(company_name=..., domain=..., funding_data=..., growth_metrics=..., current_priorities=...)`. Skip if `CACHE_HIT: true` for that company.
+
+### b. Identity resolution + person research (load-bearing — corrects Codex Finding #6)
+
+`save_person_research` requires `first_name` + `last_name`, NOT `name`. `save_discovered_person` requires `person_id` from a prior save step. So Step 7 is a 2-step backend dance:
+
+1. **Split full_name** if `first_name`/`last_name` aren't already set:
+   - Last-space heuristic: split on the last space. `Jane Smith` → first=`Jane`, last=`Smith`. `Jane van der Merwe` → first=`Jane`, last=`van der Merwe`.
+   - **Override with Phase B canonical names** if `fetch_linkedin_data` returned them. LinkedIn's `first_name`/`last_name` fields are authoritative; the heuristic is a fallback for candidates without `linkedin_url`.
+
+2. **Call `save_person_research(first_name=..., last_name=..., company=..., linkedin_url=..., email=..., topics_of_interest=..., recent_posts=..., opening_hooks=..., role_start_date=...)`.**
+   - If the prospect already had `person_id` set on the candidate (e.g. operator pasted a Vruum person UUID), pass it explicitly: `save_person_research(person_id=..., ...)` — backend updates rather than creating a new record.
+   - The response includes the `person_id`. Capture it for step c.
+
+### c. Save discovered person (the backend authoritative gate runs here)
+
+Call `save_discovered_person(person_id=<from b>, segment_id=...)`. This:
+- Runs server-side `analyze_person_match` + signal eval
+- Returns `match_score` (0–100) and `quality_gate_pass` (bool, true iff `match_score >= 70`)
+- Writes the `company_people` row that puts the prospect into the segment
+
+**Distinguish two failure modes (Codex Finding #9):**
+- **Request failure (5xx, timeout, network):** retry once with 2s backoff. If still failing, leave the prospect in `discovery_failed` status and surface in the final report. **Don't** claim "saved as gate-fail" — the row was never written.
+- **Request success + low score (`quality_gate_pass: false`):** the prospect IS saved with research; backend marks gate-fail; surface for operator review. This is a soft-fail. The prospect is on file with full research, useful for future segments.
+
+### d. Bulk enrollment (only after all prospects saved)
+
+Collect all `person_id`s where `harness_gate_status == pass` AND backend `quality_gate_pass == true` AND `mode == save-and-enroll`. Then call `bulk_start_outreach(person_ids=[...], segment_id=...)` ONCE at the end of Step 7.
+
+- Per-prospect outcomes are returned (enrolled | skipped | failed). Surface per-prospect failures in the report.
+- If `harness_gate_status` is `warming` or `low_priority`, exclude from the bulk enroll list. Operator decides on review.
+- If `mode != save-and-enroll`, skip enrollment entirely; operator handles via `/outreach-triage` later.
+
+---
+
+## Step 8 — Aggregate report (chat + audit log)
+
+Print to chat AND write to `.context/runs/pipeline-fill-{ISO-timestamp}.md` (workspace-local; `.context/` is gitignored per CLAUDE.md). Format identical for both surfaces.
+
+```
+Pipeline fill complete: {segment_name} (source: {source}, mode: {harness|platform})
+
+Candidates flow:
+  source       : {N from source skill output}
+  pre-flight   : {after dedup, after company-cache hit}
+  phase A      : {company subagents fired} ({cached_skip} skipped via cache)
+  phase B      : {prospect subagents fired} ({linkedin_unavailable} dismissed)
+
+Harness pre-filter gate:
+  pass         : {N}
+  warming      : {N}
+  low_priority : {N}
+  gate_inconclusive : {N}
+  dismiss      : {N}  (top reasons: acv_too_low={N}, decision_maker_junior={N})
+
+Backend authoritative gate (match_score >= 70):
+  passed       : {N}
+  failed       : {N}  (saved with research; operator can review via /enrich-prospect)
+  request_failed : {N}  (retry candidates — surface in next run)
+
+Enrolled (both gates pass + auto-enroll mode): {N}
+Saved but not enrolled: {N}
+
+Triggers detected (top 5):
+  - "raised $5M Series A" — {N} prospects
+  - "hired Head of Sales" — {N} prospects
+  ...
+
+Pool status: healthy | drying up | exhausted ⚠️
+
+Audit log written: .context/runs/pipeline-fill-{timestamp}.md
+```
+
+For multi-segment runs, group the report by segment and include a totals summary at the bottom.
+
+---
+
+## Edge cases + failure handling reference
+
+- **Source returns empty after dedup** — orchestrator says "All {N} candidates already in pipeline, nothing to research" and exits cleanly.
+- **Mid-flight cancellation** (operator Ctrl+C between Phase A and Phase B) — Phase A research is saved server-side. Re-running `/pipeline-fill` for the same segment + source picks up via batch dedup; no re-research of cached companies. Note this in the cancellation message.
+- **Subagent timeout cascade** — Phase A failed for a company → Phase B runs degraded → harness gate marks `gate_inconclusive` → backend decides via cached company research. See Step 4.
+- **Two-gate disagreement** — harness pass + backend fail (or vice versa) → see Step 7c. Stricter outcome wins for enrollment; both states surfaced in the report.
+- **Cached company research >90 days old** — Phase A re-runs the company subagent. Don't trust stale signals for an active fill.
+- **Manual-list cap** — if >100 lines pasted, orchestrator asks "{N} prospects pasted — process all, or first M? (a/N)".
+- **CSV >200 rows** — same prompt at Step 5 of csv-pipeline-fill.
+- **LinkedIn rate-limit (Unipile 429)** — Phase B subagent dismisses with `linkedin_data_unavailable`; orchestrator surfaces in report; operator reruns later.
+- **Unicode multi-token surnames** — `Maria Del Carmen Garcia`: heuristic splits to first=`Maria Del Carmen`, last=`Garcia` (last space wins). When `linkedin_url` is present, `fetch_linkedin_data` overrides with canonical names. Imperfect for candidates without LinkedIn URL — operator can edit via `update_person_contact` post-import.
+
+---
+
+## Canonical Handoff Prompt (for source skills)
+
+When a HARNESS source skill completes its sourcing flow and has a candidate list ready, it ends with **this exact confirmation gate** (do not paraphrase — predictable behavior matters):
+
+```
+Candidate list ready: {N} prospects from {source}.
+
+NEXT: invoke /pipeline-fill Step 3 onward (deep research → harness gate → save) with this list and segment {segment_id}.
+
+Continue automatically? (y/n)
+```
+
+- Operator answers `y` → orchestrator continues into Step 3 (this engine's flow).
+- Operator answers `n` → source skill exits cleanly with the candidate list printed in chat for inspection. The list can be passed back later by re-running `/pipeline-fill` with the list pasted.
+- Operator answers anything else → repeat the prompt; treat ambiguous responses as "ask again," not as silent default.
+
+This pattern eliminates the implicit "now follow Step 3" hand-off that would otherwise depend on attention drift. Source skills that don't end with this exact prompt are the source of "the skill stopped halfway" bug reports.

package/skills/pipeline-fill/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: pipeline-fill
 description: >-
-  Fill your outreach pipeline by importing new Sales Navigator prospects.
-  Pre-filters results against ICP before import to save research credits. Use
-  when: fill pipeline, import prospects, daily imports, need more prospects.
+  Source-agnostic pipeline orchestrator. Picks a source per segment (Sales Nav /
+  YC / CSV / discovery), runs harness deep research, applies a pre-filter gate,
+  then saves into the segment via the backend authoritative match_score>=70
+  gate. Use when: fill pipeline, import prospects, daily imports, need more
+  prospects, discover prospects from scratch, deep research before import.
 ---
 
 ## Auto-update check
@@ -17,116 +19,146 @@ Never block skill execution on this check.
 
 # Pipeline Fill
 
-You are a pipeline filling orchestrator. Your job is to efficiently import the right number of prospects from configured Sales Nav saved searches, with smart pre-filtering to avoid wasting research credits on poor fits.
+You are a source-agnostic pipeline filler. You pick segments to fill, pick a source per segment (Sales Nav / YC / CSV / discovery), and orchestrate harness deep research that gates against the segment ICP before saving prospects into the backend pipeline.
 
 ## Why this skill exists
 
-Filling your pipeline manually (preview search → evaluate each profile → dismiss mismatches → import fits → assign to segment → start outreach) takes an hour or more per day. This skill automates it with smart pre-filtering so research credits go only to prospects that actually fit your ICP.
+Filling your pipeline by source-of-the-day is normal. Sales Nav drying up doesn't mean you're stuck — pick YC, paste a CSV, or run discovery (paste candidates OR describe an ICP and the harness sources them via WebSearch + Vruum MCP + LinkedIn search). This skill orchestrates deep research per prospect in your IDE (your compute), pre-filters against segment ICP, then saves the qualified ones into the segment via the backend's canonical gate.
+
+## Where the heavy logic lives
+
+Steps 3–8 (pre-flight, Phase A research, Phase B research, harness gate, save chain, audit-log report) are defined in `RESEARCH-ENGINE.md` (in this same skill directory). This skill owns:
+- Step 1: segment picker (with ETA)
+- Step 2: source picker (conditional PLATFORM block + always-visible HARNESS block)
+- The discovery-mode handler (paste candidates inline OR describe an ICP and source via harness tools)
+- The multi-segment grammar
+
+When you reach Step 3, **stop and read** `RESEARCH-ENGINE.md`. That doc is the canonical source for the candidate-list shape, the harness gate criteria, the identity-resolution save chain, and the canonical handoff prompt that source skills use.
 
 ## Subagent architecture
 
-This skill uses the custom agent `vruum-pipeline-filter` defined at `~/.claude/agents/vruum-pipeline-filter.md`. That agent has:
-- Full Vruum MCP access via `mcpServers` (can call preview_sales_nav_search, mcp_dismiss_sales_nav_profiles, import_from_sales_nav)
-- Complete filtering instructions baked into its system prompt
+This skill uses two subagents (defined in `.claude/agents/`):
+- `vruum-company-deep-researcher` — Phase A, one per unique company in the batch (max 10 in parallel)
+- `vruum-prospect-deep-researcher` — Phase B, one per person (max 5 in parallel — Phase B is rate-limited because it calls `fetch_linkedin_data`)
 
-### MCP access requirements
+### MCP access requirements (load-bearing)
 
-Subagents can only access Vruum MCP if `vruum` is configured as a user-scoped HTTP MCP server in `~/.claude.json`. Cloud MCP servers (`claude.ai Vruum`) are NOT inherited by subagents.
+Subagents can only access Vruum MCP if `vruum` is configured as a **user-scoped HTTP MCP server** in `~/.claude.json`. Cloud MCP servers (`claude.ai Vruum`) are NOT inherited by subagents.
 
 To set up: `claude mcp add --transport http --scope user vruum https://api.vruum.ai/mcp` (one-time, requires OAuth).
 
-### Dispatch methods (in order of preference)
-
-1. **Agent tool** (primary): Spawn subagents via the Agent tool. Subagents inherit local MCP servers from `~/.claude.json` and can call Vruum tools directly. Use `run_in_background=true` for parallelism.
+The orchestrator's MCP precheck at the top of Step 3 (`get_research_playbook` call) catches this misconfiguration upfront with a clear error message. Don't skip it.
 
-2. **CLI dispatch**: `claude --agent vruum-pipeline-filter --allowedTools "mcp__vruum__*,mcp__claude_ai_Vruum__*" -p "<prompt>" --output-format text --max-turns 20`. Use if Agent tool subagents can't reach MCP.
+### Dispatch methods (in order of preference)
 
-3. **Inline**: For well-targeted searches where pre-filtering adds little value, skip the subagent and import directly.
+1. **Agent tool** (primary): Spawn subagents via the Agent tool with `subagent_type: vruum-company-deep-researcher` or `vruum-prospect-deep-researcher`. Subagents inherit local MCP servers from `~/.claude.json` and call Vruum tools directly. Use `run_in_background=true` for waves; wait for the wave to complete before dispatching the next.
 
-## Pre-fill checks
+2. **CLI dispatch**: `claude --agent vruum-{company,prospect}-deep-researcher --allowedTools "mcp__vruum-local__*" -p "<prompt>" --output-format text --max-turns 20`. Use only if Agent tool subagents can't reach MCP.
 
-Before importing for any segment, check T1 send capacity:
-1. How many people are already in "new" stage (queued but not yet contacted)?
-2. What is the daily connection limit for the segment?
-3. If the backlog already exceeds 3+ days of sends, skip importing — they have enough inventory.
+3. **Inline**: For very small fills (1–3 prospects) where dispatching subagents is overhead, run the research inline in the main session.
 
-This prevents piling up prospects that won't get touched for days.
+## Inputs
 
-## Workflow
+- `prospect_list` (optional): pre-built candidate list matching the canonical shape in `RESEARCH-ENGINE.md`. If provided, skip the source-picker step and go straight to Step 3 (pre-flight). This is how source skills hand off.
+- `segment(s)`: target segment(s); multi-segment supported.
+- `mode`: `research-only` | `save` | `save-and-enroll` (default: `save-and-enroll`).
+- `gate_threshold`: minimum backend `match_score` to enroll (default: segment's existing quality_gate).
 
-### Step 1: Check what needs filling
+## Workflow — Step 1: Show pipeline status & pick segments
 
-Call `manage_sales_nav_searches` with `action="list"` to see configured Sales Nav saved searches + segment mappings, and `get_outreach_stats` to see queue depth per segment. Present a numbered table:
+Call `manage_sales_nav_searches(action="list")` + `get_outreach_stats` for queue depth + `get_segments` for non-Sales-Nav segments. Present a numbered table with **per-segment ETA**:
 
 ```
 Pipeline status:
 
-  1. DFW CFOs        — 12/30 (18 needed, search healthy)
-  2. Austin VPs      — 28/30 (2 needed)
-  3. Houston CTOs    — 0/20  (20 needed, search drying up ⚠️)
-  4. NYC Partners    — 0/40  (40 needed)
+  1. DFW CFOs       — 12/30 (18 needed) — harness ETA: ~16m
+  2. Austin VPs     — 28/30 (2 needed)  — harness ETA: ~3m
+  3. Houston CTOs   — 0/20  (20 needed) — harness ETA: ~18m
+  4. NYC Partners   — 40/40 ✓
 
-Which segments to fill? (all / 1,3,4 / skip 2)
+Which segments to fill? (all / 1,3 / skip 2)
+Total if all needing fill: ~37m sequential.
 ```
 
+ETA estimates: ~2s for batch Step 3 dedup + ~30s/wave Phase A + ~60s/wave Phase B (5-parallel cap on Phase B). Multi-segment ETAs are sequential.
+
 **Table rules:**
 - One row per segment, numbered sequentially
 - Show current/target counts and how many are needed
 - Flag searches that are drying up (⚠️) or accounts near capacity
 - Mark segments already at target with ✓ and don't number them
+- Show per-segment ETA so operator can budget time
+
+**Wait for the user's response.** Parse: "all", "1, 3", "skip 2", "just the CFO ones", etc. Only proceed with the selected segments.
 
-**Wait for the user's response.** They can reply with:
-- "all" — fill every segment that needs it
-- Segment numbers: "1, 3, 4" or "1 and 4"
-- Exclusions: "skip 2"
-- Natural language: "just the CFO ones", "skip anything under 10 needed"
+## Workflow — Step 2: Pick source per segment (only if `prospect_list` not provided)
 
-Parse their response and only fill the selected segments.
+Per selected segment, prompt:
 
-### Step 2: Fill selected segments
+In **public mode** (the package builder strips the PLATFORM block from this skill before publishing), the picker shows only HARNESS modes, renumbered 1–4:
 
-For each selected segment, for each active pipeline source mapping:
+```
+Source for {segment_name}?
+  HARNESS mode (your compute, in-chat deep research, visible & interruptible):
+    1. sales-nav-deep    — Sales Nav profiles + harness deep research
+    2. yc                — scrape YC directory with filters you provide
+    3. csv               — read a CSV file (path next), harness deep research
+    4. discovery         — paste candidates inline OR describe an ICP and I'll source them via WebSearch + Vruum MCP + LinkedIn search
+```
 
-#### 2a. Preview and filter via subagent
+The conditional rendering happens at package-build time, not at skill-runtime — when the orchestrator runs in operator mode it sees the 6-option block; when it runs in public mode (stripped package) it sees only the 4-option block. Source-skill dispatch logic below uses option labels (`sales-nav-platform`, `yc`, etc.), not numbers, so the renumbering is cosmetic.
 
-Dispatch a subagent via the Agent tool to handle the full preview → filter → import flow. The subagent prompt should include:
-- Search name or ID
-- Segment ID or name
-- Number of profiles to import
-- Instructions to call `preview_sales_nav_search`, evaluate profiles against ICP, dismiss poor fits, and import the good ones with `auto_enroll=true`
+Per source pick, dispatch:
 
-**Parallelism:** Each search/segment mapping is independent. Spawn multiple subagents in parallel using `run_in_background=true`.
+- `sales-nav-platform` → invoke `/sales-nav-platform-fill` (calls `import_from_sales_nav`; backend handles everything; **skip Steps 3-8 of this skill entirely** — backend agents own the rest).
+- `csv-platform` → invoke `/csv-platform-fill` (calls `start_csv_import`; backend handles everything; same — skip Steps 3-8).
+- `sales-nav-deep` → invoke `/sales-nav-deep-fill` to produce a candidate list, then continue to Step 3 with it.
+- `yc` → invoke `/yc-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
+- `csv` → invoke `/csv-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
+- `discovery` → use the discovery-mode handler below to produce a candidate list (handler branches: paste-shaped input → parse, prose ICP brief → harness sources via WebSearch + Vruum MCP + LinkedIn search), then continue to Step 3 with it.
 
-#### 2b. Fallback for simple cases
+**Multi-segment behavior:** segments run sequentially. Segment 1's Step 7 (save chain + bulk enroll) completes before segment 2's Step 3 starts. Predictable rate-limit behavior, simple progress narrative. Trade-off: 3-segment fills are ~37min wall-clock vs ~22min if Phase A/B were overlapped across segments. Cross-segment overlap is a v2.
 
-If the search is well-targeted (title + location filters match the segment ICP closely), skip the subagent and import directly:
+## Discovery-mode handler (for `discovery` source)
 
-```
-import_from_sales_nav(search="DFW CFOs", count=50, segment="dfw-cfos", auto_enroll=true)
-```
+Discovery mode covers two paths off the same prompt:
+
+**Path A — operator pastes candidates** (you already know who you want)
+Tolerant line parser, candidates produced directly:
+
+- **Line is a LinkedIn URL** (matches `^https?://(www\.)?linkedin\.com/in/[^/?]+/?(\?.*)?$`) → set `linkedin_url`, leave `name` and `company` null. Phase B will fill them via `fetch_linkedin_data`.
+- **Line has comma(s)** → split as `name, company[, linkedin_url][, email]`. If 4 fields, last is email. If 3 fields, last is linkedin_url IF it matches the LinkedIn URL pattern, else interpret as email if it has `@`, else treat as a 2-field line + extra junk.
+- **Line is just text** → treat as `full_name`, prompt operator: "what company for {full_name}?". If the operator gets prompted for >3 lines, ask once "set company={X} for all unspecified?" to batch.
+
+Drop blank lines and lines starting with `#` (treat as comments).
+
+**Cap at 100 lines** by default. Above that, ask: "{N} prospects pasted — process all, or first M? (a/N)". Keeps operators from accidentally kicking off a 1,000-prospect harness fill.
 
-Use the subagent only when the search is broad enough that pre-filtering saves meaningful cost.
+**Path B — operator describes an ICP** (you want the harness to discover candidates)
+Operator gives a brief like "Series A-C SaaS founders, US, 50-500 ppl" or "directors of operations at MSPs in DFW, recently posted about hiring". Harness sources candidates from scratch:
 
-### Step 3: Report results
+1. **Anchor on segment ICP** — read the segment's existing ICP/company profile (via `get_segment` and `get_company_profile`) and merge with the operator's brief. Show a one-line synthesis ("OK so: Series A-C SaaS, US, 50-500 ppl, founder/CEO/CTO titles") and confirm before sourcing.
+2. **Source companies first** — use harness tools to find candidate companies matching the brief:
+   - `WebSearch` for funding announcements, news, lists ("Series A SaaS 2026", "TechCrunch Series B SaaS announcements")
+   - `WebFetch` on Crunchbase / PitchBook / company directories
+   - `mcp__vruum-local__search_linkedin_people` for company-fitting roles when the brief is people-shaped (e.g. "VPs of Eng at Series A SaaS")
+3. **Source people from each company** — for each candidate company, use `mcp__vruum-local__find_people_at_company` (Unipile-backed; respects LinkedIn rate limits) to find titles matching the segment ICP. Cap at ~5 people per company to spread the discovery surface.
+4. **Dedup against existing pipeline** — for each discovered person, check `mcp__vruum-local__search_existing_people` so you don't research someone the segment already has.
+5. **Show the discovered list to the operator** before handoff. Format: `Name (title) — Company [linkedin]`. Cap the surface at 2x daily_target so we don't over-source. Get a "go" / "drop X" before continuing.
 
-After the fill completes, present a summary:
+Discovery-path candidates produced in either path use the canonical shape in `RESEARCH-ENGINE.md` and feed into Step 3 the same way.
 
-"Pipeline fill complete:
-- DFW CFOs: Previewed 45 profiles, approved 32, dismissed 13. Imported 18 new.
-- Austin VPs: 2 more imported.
-- Houston CTOs: Search drying up — returned only 7 profiles. Consider broadening the search or creating a new one.
-Total: 27 imported, 13 dismissed, ~$3.40 saved by pre-filtering."
+**Path detection:** if the first non-comment line looks like a URL or has commas (paste-shaped), use Path A. If it's prose without URLs/commas and >40 chars, use Path B. If ambiguous, ask: "paste, or describe the ICP and I discover?"
 
-## Shared search deduplication
+## Workflow — Steps 3 onward
 
-Multiple segments may use the same Sales Nav saved search (e.g. "Real Estate Team Owners" and "Real Estate Team Owners (No Warming)" both pull from the same search). **Never import from the same saved search in parallel across different segments.** Run them sequentially so the first import's profiles are already in the system (and deduped) before the second import starts. Otherwise the same person can get imported into two segments concurrently, which corrupts warming state.
+**Switch to `RESEARCH-ENGINE.md` here.** Read that doc and follow Step 3 (pre-flight) → Step 4 (Phase A) → Step 5 (Phase B) → Step 6 (harness gate) → Step 7 (save chain with identity resolution) → Step 8 (aggregate report + audit log to `.context/runs/`).
 
-Before dispatching subagents, group segment fills by their saved search ID. Within each group, dispatch sequentially. Different saved searches can still run in parallel.
+Do not duplicate the engine logic in this skill — link operators back to the engine doc when they ask "what does the gate check?" or "how does the save chain work?"
 
 ## Notes
 
-- Each mapping is independent. If one fails (expired LinkedIn session, rate limit), others still run.
-- The 5-minute cooldown on automated pipeline fills prevents duplicate imports if the skill runs twice in quick succession.
-- Pre-filtering saves ~$0.10-0.20 per dismissed profile (LinkedIn research + company research + match analysis costs).
-- If a search returns fewer profiles than needed, flag it as "drying up" so the user knows to create a new search or broaden targeting.
-- If subagent MCP connections fail, fall back to inline: preview in the main session, filter manually, import directly. This typically means `vruum` isn't in `~/.claude.json`.
+- **Composability** with source skills: source skills produce candidate lists; this orchestrator runs the research engine. Both directions allowed (operator can run a source skill standalone or run /pipeline-fill as the front door).
+- **Real money costs** are in Phase B (LinkedIn API + Hunter calls + OpenAI tokens for the prospect subagent). Phase A is mostly WebFetch/WebSearch which is operator-network. The batch primitives in Step 3 keep dedup latency low (~2s vs 12s pre-batch).
+- **Harness offload framing**: deep research runs in your IDE (your tokens). The backend `MatchAnalysisAgent` runs the canonical gate (~$0.02/prospect on Vruum's bill). This split is intentional — see memory `project_harness_offload_strategy.md`.
+- **Audit trail**: every run writes to `.context/runs/pipeline-fill-{ISO-timestamp}.md`. Useful weeks later for "what did the YC fill on Apr 12 import?"

package/skills/sales-nav-deep-fill/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: sales-nav-deep-fill
+description: >-
+  Sales Nav harness source for /pipeline-fill. Pre-filters Sales Nav profiles
+  via vruum-pipeline-filter, produces a candidate list, hands off to
+  /pipeline-fill for deep research and import. Use when: sales nav with deep
+  research, sales nav harness mode, in-chat sales nav.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to this repo). Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention the available upgrade in one line and offer `/vruum-upgrade`. Then continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, then continue.
+- Empty → proceed silently.
+
+Never block skill execution on this check.
+
+# Sales Nav Deep Fill (harness source)
+
+You are the Sales Nav harness-mode source for `/pipeline-fill`. You produce a candidate list from a Sales Nav saved search and hand off to the orchestrator for deep research, harness gate, and save chain.
+
+**This is the harness counterpart to `/sales-nav-platform-fill`.** The platform skill calls `import_from_sales_nav` and lets backend agents do everything (Vruum's compute). This skill stops at producing a candidate list — Phase A and Phase B run in your chat session (your harness compute), and `save_discovered_person` is called only after the harness pre-filter gate passes. Pick this when you want visibility into the deep research as it happens.
+
+## Inputs
+
+- `segment`: target segment (single — multi-segment lives in `/pipeline-fill`)
+- `count`: how many profiles to pre-filter (default 30)
+
+## Workflow
+
+### Step 1: Preview Sales Nav profiles
+
+Call `preview_sales_nav_search(segment=..., count=...)`. Returns profile data + segment ICP context (target_titles, target_industries, value_proposition, positioning_angle, differentiators).
+
+### Step 2: Dispatch `vruum-pipeline-filter` for ICP pre-filter
+
+Spawn the existing `vruum-pipeline-filter` subagent (defined at `.claude/agents/vruum-pipeline-filter.md`). It evaluates each profile against the segment ICP using cheap title/company matching — no LinkedIn API calls, no deep research. APPROVE / DISMISS per profile.
+
+This is the cheap pre-filter — it removes obvious mismatches (titled-wrong, industry-wrong) before they enter Phase A/B deep research. Saves ~8 minutes per fill on a 30-profile preview that has 10 mismatches.
+
+### Step 3: Build candidate list
+
+Take the APPROVED profiles from Step 2 and convert them to the canonical candidate-list shape. From each profile, capture:
+- `full_name` (from profile name)
+- `company` (from profile current company)
+- `linkedin_url` (canonicalize via the LinkedIn URL in the profile)
+- `title` (current title — useful for downstream classification but Phase B re-fetches authoritatively)
+- `email`: null (Phase B finds it)
+- `person_id`: null (resolved in Step 7 of engine flow)
+- `raw_signals`: `{source: "sales-nav-deep", search_id: ..., preview_metadata: {...}}`
+
+### Step 4: Hand off to /pipeline-fill (canonical handoff prompt)
+
+Emit the canonical handoff prompt (defined in `pipeline-fill/RESEARCH-ENGINE.md` — the canonical handoff section):
+
+```
+Candidate list ready: {N} prospects from sales-nav-deep.
+
+NEXT: invoke /pipeline-fill Step 3 onward (deep research → harness gate → save) with this list and segment {segment_id}.
+
+Continue automatically? (y/n)
+```
+
+- Operator answers `y` → continue into the engine doc's Step 3.
+- Operator answers `n` → exit cleanly with the candidate list visible in chat.
+
+## Notes
+
+- **For the operator:** pick this when you want to see the deep research happen, want to interrupt mid-stream, or want zero platform compute cost on the front-half (sourcing + research). The back-half (`save_discovered_person`'s `analyze_person_match` + `match_score >= 70` gate) still runs on Vruum, intentionally — it's the canonical gate.
+- **Don't call `import_from_sales_nav` directly from this skill.** That triggers the backend research pipeline, which is exactly what we're avoiding by being in harness mode. If you need the backend path, use `/sales-nav-platform-fill` instead.
+- **vruum-pipeline-filter pre-filter is FREE** for the operator (cheap title/company match). The expensive Phase B research only fires on prospects that survive that filter.

package/skills/segment-doctor/SKILL.md

@@ -85,7 +85,7 @@ Root causes (ranked):
    → Recommendation: Shift channel mix to prioritize LinkedIn
 
 4. **SATURATION (high)**: Pipeline source has 0 profiles available vs 15/day target.
-   → Recommendation: Broaden your Sales Navigator saved search criteria, then run `/pipeline-fill` to add volume.
+   → Recommendation: Broaden your Sales Navigator saved search criteria, then run `/pipeline-fill` to add volume. (`/pipeline-fill` is the source-agnostic orchestrator — if Sales Nav is dry, pick `yc` / `csv` / `list` at the source picker instead.)
 
 Want me to apply any of these fixes?"
 

package/skills/yc-pipeline-fill/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: yc-pipeline-fill
+description: >-
+  YC harness source for /pipeline-fill. Scrapes YC's public Algolia index,
+  extracts founder LinkedIn URLs, dedups, hands a candidate list to
+  /pipeline-fill for deep research and import. Use when: YC pipeline fill,
+  source from YC, fill segment with YC founders, sales nav dried up, source YC.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to this repo). Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention the available upgrade in one line and offer `/vruum-upgrade`. Then continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, then continue.
+- Empty → proceed silently.
+
+Never block skill execution on this check.
+
+# YC Pipeline Fill (harness source)
+
+You are the YCombinator harness-mode source for `/pipeline-fill`. You scrape YC's public directory, extract founder LinkedIn URLs, dedup, and hand a candidate list to the orchestrator. No deep research, no harness gate, no save chain in this skill — that's all in `pipeline-fill/RESEARCH-ENGINE.md`.
+
+This is the answer to "DFW CFOs Sales Nav is dead, what now?" — pivot to YC, get 30 founders into the segment in ~15 minutes.
+
+## Inputs
+
+- `segment`: target segment (single)
+- `count`: target number of imports (default 50)
+- `filters` (REQUIRED — no defaults; operator must specify at least one):
+  - `team_size_min` / `team_size_max` (proxy for funding stage)
+  - `launched_at_after` / `launched_at_before` (Unix ts; YC batch recency)
+  - `industries` (e.g. ["B2B"])
+  - `tags` (e.g. ["SaaS", "Fintech", "DevTools"])
+  - `regions` (e.g. ["United States"])
+
+If the operator runs the skill without filters, prompt: "YC has 5K+ companies — give me at least one filter (e.g. 'last 18 months, team 11-50, B2B SaaS')." Don't apply silent defaults — defaults shape the funnel invisibly.
+
+## Workflow
+
+### Step 1: Load segment ICP
+
+Call `get_research_playbook(segment_id=<id>)` to load ICP context. The downstream subagents need it for classification; capture it now to pass forward.
+
+### Step 2: Algolia connectivity precheck
+
+Issue a one-shot Algolia query against the index with `hitsPerPage: 1` to confirm extraction works. **Do NOT use `manage_sales_nav_searches(action="accounts")`** as a precheck — that endpoint checks LinkedIn account state and has nothing to do with YC. False-fails operators who don't have Sales Nav configured (eng review §1B).
+
+The precheck happens implicitly in Step 3 (the first real Algolia call); if it fails there, abort with a clear error.
+
+### Step 3: Fetch rotating Algolia API key
+
+```
+curl -sL https://www.ycombinator.com/companies > /tmp/yc-home.html
+```
+
+Extract the Algolia API key with regex `[A-Za-z0-9]{200,}` from the HTML — there's typically one match (a 256-char base64 string). The key is a scoped key with embedded YC restrictions:
+- `analyticsTags=ycdc`
+- `restrictIndices=YCCompany_production%2CYCCompany_By_Launch_Date_production`
+- `tagFilters=%5B%22ycdc_public%22%5D`
+
+Try the extracted key against the Algolia endpoint (Step 4). If multiple `[A-Za-z0-9]{200,}` matches exist, try each in order; the working one returns `hits`, others return `{"message":"Invalid API key"}` or 403.
+
+**If all candidates fail**, abort with: "YC homepage structure changed — Algolia key extractor needs updating. Inspect `/tmp/yc-home.html` and adjust the regex." Don't silently fall back. The key rotates on every server-side render — don't cache across runs.
+
+### Step 4: Query Algolia
+
+```
+POST https://45bwzj1sgc-dsn.algolia.net/1/indexes/YCCompany_By_Launch_Date_production/query
+Headers:
+  x-algolia-api-key: <extracted key>
+  x-algolia-application-id: 45BWZJ1SGC
+  content-type: application/json
+Body:
+{
+  "query": "",
+  "hitsPerPage": <count * 3>,
+  "page": 0,
+  "facetFilters": [<derived from filters>],
+  "numericFilters": [<derived from filters>]
+}
+```
+
+**Filter mapping:**
+- `team_size_min/max` → numericFilters: `team_size>=N` / `team_size<=N`
+- `launched_at_after/before` → numericFilters: `launched_at>=ts` / `launched_at<=ts`
+- `industries` → facetFilters array: `[["industries:Fintech", "industries:SaaS"]]` (OR within one filter)
+- `tags` → facetFilters: `[["tags:B2B"]]`
+- `regions` → facetFilters: `[["regions:United States"]]`
+
+Request `count * 3` hits to allow for dedup + research-stage drops. Capture per hit: `slug`, `name`, `website`, `team_size`, `batch`, `one_liner`, `long_description`, `tags`, `all_locations`.
+
+### Step 5: Per-company page scrape (parallelizable, free)
+
+For each candidate:
+
+```
+curl -sL https://www.ycombinator.com/companies/{slug}
+```
+
+The page is HTML-entity-encoded. Decode entities first:
+
+```
+curl -sL https://www.ycombinator.com/companies/{slug} | python3 -c "import html,sys;print(html.unescape(sys.stdin.read()))"
+```
+
+After decoding, regex out:
+
+- **Founders array**: `"founders":\[(.*?)\]` — extract per-founder `"full_name":"([^"]+)"`, `"title":"([^"]*)"`, `"linkedin_url":"([^"]+)"`
+- **News items**: `"newsItems":\[(.*?)\]` — extract per-item `"title":"..."`, `"url":"..."`, `"date":"..."`. Filter to last 12 months by parsing the date strings (format like "May 09, 2023"). Useful triggers for the orchestrator's harness gate.
+
+**Pick primary founder:**
+1. First founder where `title` matches `/CEO|Chief Exec|Co-?founder & CEO/i` (case-insensitive)
+2. Else first founder where `linkedin_url` is non-empty
+3. Else **drop the company entirely.** Do not call `find_person_linkedin` to guess — produces low-confidence matches and noise.
+
+**HTML revision detection:** If >30% of candidates yield zero founders (regex didn't match), abort the run with: "YC company page structure changed — scrape regex needs updating." Don't silently degrade. Single-company misses are tolerable.
+
+### Step 6: Build candidate list
+
+Convert each surviving company into a candidate matching the canonical shape (defined in `pipeline-fill/RESEARCH-ENGINE.md`):
+
+```
+{
+  full_name: <founder full_name>,
+  first_name: null,  // engine resolves in Step 7
+  last_name: null,
+  company: <yc company name>,
+  linkedin_url: <founder linkedin_url, canonicalized>,
+  email: null,        // Phase B finds it
+  person_id: null,    // engine resolves in Step 7
+  title: <founder title>,
+  raw_signals: {
+    source: "yc",
+    yc_slug: <slug>,
+    yc_batch: <batch>,
+    yc_team_size: <team_size>,
+    yc_tags: <tags>,
+    yc_locations: <all_locations>,
+    yc_one_liner: <one_liner>,
+    yc_news: <filtered news items, last 12mo, with title/url/date>
+  }
+}
+```
+
+The `yc_news` entries are pre-loaded triggers — Phase A's company subagent uses them in lieu of an extra WebSearch.
+
+### Step 7: Pool exhaustion check
+
+If the Algolia query returned `< count` total hits even before dedup:
+- < 5 hits left → flag: "YC pool for these filters is exhausted — broaden filters or fall back to Sales Nav."
+- < 20% pass-rate after dedup + founder-filter → flag: "YC pool drying up — consider broadening filters next run."
+
+Embed the pool status in the candidate-list metadata so the orchestrator's report can surface it.
+
+### Step 8: Hand off to /pipeline-fill (canonical handoff prompt)
+
+Emit the canonical handoff prompt (defined in `pipeline-fill/RESEARCH-ENGINE.md`):
+
+```
+Candidate list ready: {N} prospects from yc.
+
+NEXT: invoke /pipeline-fill Step 3 onward (deep research → harness gate → save) with this list and segment {segment_id}.
+
+Continue automatically? (y/n)
+```
+
+- Operator answers `y` → continue into the engine doc's Step 3.
+- Operator answers `n` → exit cleanly with the candidate list visible in chat.
+
+## Edge cases
+
+- **Algolia key extraction fails** (no candidates work): abort, single-line error pointing at the homepage structure.
+- **>30% scrape failure**: abort, point at the company-page structure.
+- **No founder LinkedIn for a company**: drop the company; never guess via `find_person_linkedin`.
+- **Pool exhaustion**: flag in candidate list metadata so the orchestrator's report surfaces it.
+- **Operator gives no filters**: prompt for at least one. No silent defaults.
+- **Operator gives `count` of 200+**: still works; expect ~30+ minute wall-clock for the full pipeline-fill flow.
+
+## Notes
+
+- **Sourcing phase is purely scrape-based** — no MCP/LinkedIn calls. Cheap to run repeatedly with different filters to find the right batch before committing to deep research downstream.
+- **YC batch recency**: filter `launched_at_after` to the past 18 months gives a Series-A-shaped pool — most likely to clear ACV gates downstream. But don't apply silently; the operator should choose.
+- **Algolia key rotation**: the key in YC's homepage HTML rotates on every server-side render. Don't cache across runs. The single-fetch-per-run pattern is correct.
+- **Composability with /pipeline-fill**: this skill produces a candidate list. The orchestrator runs the engine. Operator can also run this skill standalone for "I just want YC, today" — answer `y` at the handoff prompt to continue into research.