# prospecting — feature docs

Top-level V4 feature owning the prospect lifecycle: from first cross-surface touch through qualification, warm-intro, conversion, and (v2) overflow routing into a peer marketplace.

## Why a top-level feature

Prospecting was incubated inside `ai-copilot/` because the first specialist (`specialist-prospect-resolver`) shipped under the copilot fleet. It has since grown four distinct AI-facing concerns that share a single source of truth (`prospects` + `prospect_touchpoints` tables on `platform.db`):

1. **Cross-provider prospect graph** — consented, dynamically-generated prospect profiles whose signal is pooled across providers to lift conversion and qualification quality.
2. **AI-mediated warm intros** — two copilots negotiate an introduction on behalf of their humans, surfacing only when both sides' agents agree it's worth the interrupt.
3. **Prospect auto-qualify + draft** — the free-time lever: triage + draft-message automation that converts inbound prospects to bookings with minimum provider work.
4. **Internal beauty-services marketplace** (v2) — providers route overflow / idle slots to vetted peer allies via the same prospect graph.

Promoting prospecting to its own feature folder makes those concerns addressable independently while keeping their data plane unified.

## Interface posture

**AI is the primary interface.** Each subfeature ships first as a specialist contract (`*.contract.md`) consumed by the platform's copilot fleet. The corresponding `*.screen.md` describes the *secondary, low-priority* web FE under `prospecting/web-fe/` — useful for ops, support, and the few providers who want a non-conversational surface, but not the daily driver.

**Single API plane.** All four subfeatures call **`platform.api` on black** (per `INFRA.md §4`, port 3060) — no new API service, no dev API stack, no per-feature gateway. New endpoints land as additional routes on the existing NestJS data plane.

**Person-first tenancy.** Every new table or row introduced here carries `user_id` (Person) and optional `org_id` (Org) per `DESIGN.md §5`. Cross-provider sharing is opt-in at the Person level and never auto-promotes prospect rows across provider boundaries (see `Y-cross-org-marketplace.brief.md §Y4`).

## Doc inventory

| Subfeature | Brief | AI contract | Web FE screen |
|------------|-------|-------------|---------------|
| Cross-provider prospect graph | `cross-provider-graph.brief.md` | `cross-provider-graph.contract.md` | `cross-provider-graph.screen.md` |
| AI-mediated warm intros | `warm-intros.brief.md` | `warm-intros.contract.md` | `warm-intros.screen.md` |
| Prospect auto-qualify + draft | `auto-qualify-draft.brief.md` | `auto-qualify-draft.contract.md` | `auto-qualify-draft.screen.md` |
| Internal marketplace (v2) | `internal-marketplace.brief.md` | `internal-marketplace.contract.md` | `internal-marketplace.screen.md` |

Plus the parent product brief: `prospecting.brief.md`.

## Files pending migration (still under `ai-copilot/docs/`)

These are the canonical prospecting surfaces today; they remain in `ai-copilot/docs/` until a coordinated link-rewrite sweep moves them here. New work should *reference* them at their current path:

- `@features/ai-copilot/docs/specialist-prospect-resolver.contract.md` — cross-surface dedup, scoring, touchpoint linking, identifier hashing, photo-hash matching.
- `@features/ai-copilot/docs/prospect-detail.screen.md` — resolved prospect drawer (cross-surface message history, funnel stage, attribution).
- `@features/ai-copilot/docs/specialist-strategist.contract.md` — analytics reads over `prospect_touchpoints` + `metric_aggregates`; stays in ai-copilot (broader than prospects).

`Y-cross-org-marketplace.brief.md` and `marketplace-detail.screen.md` similarly stay in `ai-copilot/docs/` — they cover the *external* cross-org marketplace, which `internal-marketplace.brief.md` here explicitly distinguishes from.

## Naming

- Feature code-name: **`prospecting`** (provider-generic per `DESIGN.md §7`).
- Web FE deployed name: `quinn.prospecting` for Quinn's instance, `{provider}.prospecting` for peers.
- Specialist code-names: `specialist-graph-resolver`, `specialist-warm-intro`, `specialist-auto-qualify`, `specialist-marketplace-router` (the existing `specialist-prospect-resolver` continues to own dedup at the row level; the new graph specialist is one level up, operating across consented provider boundaries).

## Sequencing

1. **Now (P5):** cross-provider graph + auto-qualify+draft. These are independent of warm-intros and pay back free-time immediately.
2. **After copilot density:** warm intros. Requires both sides to have an AI copilot — cold-start brutal until copilot adoption is dense.
3. **v2:** internal marketplace. Depends on (1) shipping (graph + cross-provider trust signal) and on the external cross-org marketplace (`Y`) being live for peer-vetting primitives.