cocottetech/@platform/codebase/@features/prospecting/docs/README.md

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.