# From prospect to opportunity

A prospect becomes an opportunity when a person decides there is a deal worth working — not when a reply arrives. The conversion creates a Person, a Company where one is warranted, and an Opportunity on the pipeline. The research, the evidence and the messages are not copied across; they stay on their own records and the new ones point at them.

- **Status:** Available
- **Audience:** both
- **In the app:** #/prospects, #/pipeline, #/relationships
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/prospects/prospect-to-opportunity/

## The moment of transition

Nothing about a warm reply promotes a prospect on its own. Reply classification can mark interest, raise the prospect in the list and open a follow-up, but the pipeline is a commitment about revenue and that commitment is made by a person or by an explicit instruction. This is the same separation that runs through the rest of Connect: the engine may prepare, a person decides.

Conversion is therefore an action with a subject and a timestamp. The decision log records who did it and under which rule, so six months later the question 'why is this on the pipeline' has an answer that does not depend on anybody remembering.

## What exists afterwards

| Record | State | Owned by |
|---|---|---|
| The prospect | Kept, marked as converted, still readable | `prospecting.py` and the `prospect_*` modules |
| Person | Created, or matched to one that already exists | `people.py` |
| Company | Created or matched when the prospect is an organisation | `companies.py` |
| Identity | One row per address on one channel, attached to the Person | `identity.py` |
| Opportunity | New, on the pipeline at `#/pipeline` | `sales.py` |
| Lifecycle stage | Moved, using the vocabulary `stages()` returns | `journey.py` |

The Person and Company are matched before they are made. If the prospect's address already resolves to somebody in your relationships, conversion attaches to that Person rather than producing a second one — the same resolution described in [Resolving a prospect to an existing relationship](/docs/prospects/prospect-identity/).

## Carried across, linked, or left

**The fit reason** — Carried. It is the sentence that justified the prospect, and it is exactly what a salesperson needs on day one of the deal.
**Evidence** — Linked, not copied. A claim keeps the source it was proved from; duplicating evidence onto a deal would create a second copy that ages differently from the first.
**Messages** — Linked. Outreach and the reply stay on the conversation and appear on the Person's timeline, so the deal shows the correspondence without owning it.
**Research freshness** — Left behind. Freshness governs re-research of a prospect; a live deal is kept current by the people working it, not by a scheduled pass.
**Discovery criteria** — Left behind. The brief that found the organisation is not a property of the deal and is not carried into it.

> **Note** Converting does not delete the prospect and does not remove it from the prospect list. It is marked, so that discovery does not offer the same organisation again and the counts above the list can tell researched-but-untouched from already-in-progress.

## Doing it, and the ways it goes wrong

1. Open the prospect and read the fit reason and its evidence before anything else.
   - Result: If the evidence has aged past what freshness allows, you are converting on a claim that was true once. Re-research first.
2. Convert. The Assistant can do this too, with `create_opportunity` after `create_prospect` or from an existing prospect.
   - Result: Person, Company, Identity and Opportunity appear; the stage moves.
3. Set the stage deliberately with `move_opportunity` or `set_lifecycle_stage` rather than leaving the default.
   - Result: Pipeline reporting and the follow-up queue both read the stage, so a wrong one is not cosmetic.

**A second Person appeared** — The prospect's address had not been seen before in that exact form. Merge the duplicate — `merge_people` preserves identities, stages, follow-ups, deals, demos, cases and onboarding from both sides.
**The Opportunity has no value** — Connect does not invent a deal size and the Assistant has no pricing rights at all. Somebody has to put a number on it.
**Conversion is refused** — The prospect resolved to an existing customer. That refusal is the identity check doing its job; read it before overriding it.

## Questions

### Does Connect convert a prospect automatically when they reply warmly?

No. A warm classification changes the prospect's next action and can raise a follow-up, but creating a deal is a decision that is recorded against a person or an explicit instruction. Autonomy governs sending messages, not declaring revenue.

### If I convert by mistake, is the research lost?

No. The prospect record survives conversion with its evidence intact. Removing the opportunity leaves the prospect where it was, still researched and still marked as touched so discovery does not re-offer it.

### What happens to outreach already in flight?

It continues under the rules it was sent with, and any reply is classified as before. Conversion changes where the relationship is managed; it does not silently cancel a sequence. Stopping a cold sequence is its own action.

## Related

- [Prospecting in Connect](https://connectbyjbrh.com/docs/prospects/)
- [A prospect replies](https://connectbyjbrh.com/docs/prospects/prospect-reply/)
- [Resolving a prospect to an existing relationship](https://connectbyjbrh.com/docs/prospects/prospect-identity/)
- [Sales in Connect](https://connectbyjbrh.com/docs/sales/)
- [From prospect to client, end to end](https://connectbyjbrh.com/docs/workflows/prospect-to-client/)
- [Relationships in Connect](https://connectbyjbrh.com/docs/relationships/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §4 and §5 — prospecting stages and the relationship model
- `backend/app/sales.py`, `backend/app/journey.py` — opportunities and lifecycle stages
- `backend/app/people.py`, `backend/app/companies.py`, `backend/app/identity.py`
- Connect capability registry (`docs-source/facts.py`)