# Discovering prospects, end to end

A discovery run turns a written description of who you want to reach into researched organisations with evidence behind every claim. It reads public sources, discards the businesses you already know, scores what remains against your brief, and stops. Nothing is sent by discovery, and no address is created that a source did not show.

- **Status:** Available
- **Audience:** both
- **In the app:** #/prospects, #/activity, #/billing
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/prospect-discovery/

## The run, stage by stage

1. Trigger — a person runs discovery from `#/prospects`, the Assistant calls `discover_prospects`, or a background pass continues an existing brief.
2. User event — the brief itself: the description of who you want to reach and the location scope that bounds it.
3. Authentication and workspace resolution — the session is identified and the workspace entered before any brief, entitlement or relationship is read.
4. Ingest — `prospect_discovery_query` turns the written brief into the queries that will actually be run.
5. Canonical record — candidates are recorded before research, so a run that fails halfway leaves evidence of what it had reached.
6. Research and reasoning — public sources are read per candidate; claims are extracted with their source attached; `prospect_scoring` scores what survives against the brief.
7. Knowledge, memory and rules — the workspace's own knowledge shapes what counts as a fit, and directives such as `block:<channel>` are read from the tag list rather than from prose.
8. Autonomy and approval — the AI budget is asked before paid work begins; a deeper pass is a routed decision, never an automatic escalation.
9. Action through a provider — model calls and public-source fetches. No message is sent to anybody at this stage, on any channel.
10. Result — qualified prospects with written fit reasons, plus researched prospects that have no contact address and are kept anyway.
11. Relationship and timeline — candidates that resolved to somebody you already know appear as the existing relationship instead of as a new prospect.
12. Audit, usage and Needs You — the spend is booked to the ledger, refusals are recorded with their reasons, and anything needing a person is queued.

## What you see, what changes, what breaks

| Stage | What you see | What changes | What can fail |
|---|---|---|---|
| Brief | Your description and scope | Nothing yet | A brief so broad that everything matches, or so narrow that nothing does |
| Query | A run starting | A run record | A location that cannot be resolved to anywhere |
| Candidates | A count rising | Candidate rows | Sources return nothing for this description |
| Identity resolution | Fewer prospects than candidates | Matches attach to existing relationships | A genuine prospect matched to a customer by a shared name |
| Research | Claims appearing with sources | Claims and evidence | The AI budget refuses further paid work |
| Scoring | Qualified and unqualified split | Scores and fit reasons | Thin evidence produces a thin score, correctly |
| Contactability | The gap between qualified and ready | Addresses with provenance | No address exists in any source — the prospect is kept regardless |

> **Note** The gap in the last row is the one worth reading rather than closing. Those are organisations that fit, are proved to fit, and cannot be emailed. They are kept with a different next action precisely so that the alternative — inventing an address that looks plausible — never becomes tempting.

## Gates, in the order they stop a run

1. Workspace resolution. Nothing at all happens before the run is inside the right workspace; a customer session reaches this through `tenantAdapt` and the `customer_safe` allowlist.
2. The AI budget. Paid model work is refused rather than run and billed, and the refusal is recorded.
3. Identity resolution, which removes candidates before they cost anything more than the research already done.
4. Scoring against the brief, which decides qualified from not.
5. Contactability, which decides ready-to-send from qualified — and never by manufacturing the missing part.

None of these gates sends anything, because discovery does not send. Outreach is a separate flow with its own compliance check and its own approval, and a run that ends with a hundred qualified prospects has written to none of them.

## Verified success, and the ways it disappoints

A run succeeded when the counts above the list moved and each new prospect carries a fit reason you can open evidence under. A run that produced rows with no evidence has not succeeded quietly — it cannot happen, because a claim without evidence does not reach the record.

**Nothing was found** — Four causes, in order of likelihood, and they have their own page.
**Far fewer prospects than candidates** — Identity resolution, scoring, or both. The activity trail says which.
**Everything qualified** — The brief is describing a category rather than a customer. Add the constraint that actually decides.
**The run stopped partway** — The budget refused. Candidates already researched are kept; the run resumes rather than restarting.

## Questions

### Does discovery contact anyone?

No. It reads public sources and writes records. Every outbound message in prospecting belongs to the outreach flow, which runs its own compliance check and obeys the channel's autonomy mode before anything leaves a mailbox.

### Can I run the same brief twice?

Yes. Organisations already discovered are recognised and updated rather than duplicated, so a second run is a way of extending a list rather than doubling it. It does cost research on genuinely new candidates.

### Why is a company I know is a good fit missing?

Usually one of three things: it fell outside the location scope, it resolved to somebody already in your relationships, or no public source says the thing your brief asks for. The decision trail distinguishes them.

## Related

- [Prospecting in Connect](https://connectbyjbrh.com/docs/prospects/)
- [Describing who you want to reach](https://connectbyjbrh.com/docs/prospects/discovery-criteria/)
- [Collecting candidates](https://connectbyjbrh.com/docs/prospects/candidate-collection/)
- [Discovery returned nothing](https://connectbyjbrh.com/docs/troubleshooting/no-prospects-found/)
- [Researching one prospect, end to end](https://connectbyjbrh.com/docs/workflows/prospect-research/)
- [End-to-end workflows](https://connectbyjbrh.com/docs/workflows/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §4 — the prospecting stage chain
- `docs-source/sources/GENERAL.md` §2 and §5 — request flow, autonomy and Needs You
- `backend/app/prospecting.py`, `backend/app/prospect_discovery_query.py`
- Connect capability registry (`docs-source/facts.py`)