# Creating an opportunity, end to end

Somebody signals intent, a person or the Assistant opens a deal against the relationship it came from, a value in minor units is set where one is known, and the first next action becomes a dated commitment. No message goes out as a side effect of creating the record — the sale becomes visible before anything is said about it.

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

## The stages

1. Trigger — a signal of commercial intent: a question about cost, a quantity named on a call, a prospect replying to outreach.
2. User or external event — the message or call has already arrived and been canonicalised; nothing new comes off the wire at this point.
3. Authentication and workspace resolution — the workspace is entered before any record is written, so the deal is stamped with the right owner from the first statement.
4. Ingest or request — `open_opportunity` is called from the board, from the deals sheet, or by the Assistant's `create_opportunity`.
5. Canonical record — the opportunity row is created against the Person, and through them the Company; `set_value` writes value and currency together in minor units.
6. Reasoning — what the deal is for is drawn from the conversation, not invented: the words the customer used are the best description available.
7. Knowledge, memory and rules — grounded terms may be recorded; a figure no source supports is refused rather than written to the record.
8. Autonomy and approval — creating a record needs no approval. Anything said to the customer about it does, under the channel's own rules.
9. Action through a provider — none, unless a reply or a chase is sent, in which case it passes the ordinary send boundary.
10. Result — the deal appears in its first stage on `#/pipeline` and on the deals sheet in `#/data`, with its value and its counterparty.
11. Relationship, timeline and memory — the deal joins the person's timeline and their Customer 360 beside the conversation that produced it.
12. Audit, usage and Needs You — the creation is recorded with who did it and from what; a commercial question raised at the same time lands in Needs You.

## What you see and what changes

| Stage | What you see | What changes | What can fail |
|---|---|---|---|
| Opening | A new card in the first column | One opportunity row, stamped to the workspace | It lands on the wrong person — usually a forwarded thread |
| Valuing | A figure on the card | `value_minor` and currency together | A value typed as text with separators; check one row after a bulk import |
| Linking | The person and organisation on the card | The deal points at the relationship | No company link, so colleague context is absent |
| First action | A commitment in the follow-up queue | A dated row with a reason and a channel | No reason recorded, which makes it useless to whoever inherits it |
| Saying something | A reply drafted or sent | A message, under the channel's autonomy | A commercial question inside it: refused and escalated |

## Idempotency and the duplicate deal

Nothing stops two people opening a deal for the same purchase within a minute of each other, and on a busy morning that happens. The record layer is deliberately permissive here — a deal is a judgement, and refusing to create one because a similar one exists would be wrong more often than right.

- Check the person's existing deals before opening a new one; the relationship view lists them.
- Two deals for one purchase make every column total wrong, and the error compounds because both get chased.
- Where duplicates already exist, close one as a duplicate rather than deleting it, so the history of what happened stays intact.
- Follow-ups have their own protection — identical timing for the same person is treated as one — but that does not catch two deals.

## Verified success

1. Open the person and confirm the deal is listed against them, not against a colleague of yours.
   - Result: This is the failure that is cheapest to fix now and most expensive to fix after a fortnight of activity.
2. Check the value reads correctly on the card and on the deals sheet.
   - Result: Both read the same stored integer, so a disagreement means a formatting problem worth reporting.
3. Confirm the first commitment exists with a reason and a due time.
   - Result: A deal with no next action is a deal nobody is working on, whatever column it sits in.
4. Read the decision log entry for the creation.
   - Result: It names who opened it and from what, which is the provenance the next person will want.

> **Note** If the deal came from a call, check the call's outcome as well. A commercial intent captured on the phone is worth reading in the transcript before the value is treated as agreed.

## Questions

### Does opening a deal tell the customer anything?

No. Creating the record is internal. Everything the customer experiences is a message, and messages go out under the autonomy rules of their channel.

### Can the Assistant open a deal without me?

It can, through the same service and with the same stage rules and refusals. What it cannot do is decide the commercial terms that would let that deal advance.

### What if the value is not known yet?

Open the deal without one. An opportunity with no value is honest; an opportunity carrying a guessed figure quietly corrupts every total on the board and is much harder to notice later.

## Related

- [Opportunities: the deal record](https://connectbyjbrh.com/docs/sales/opportunities/)
- [The pipeline board](https://connectbyjbrh.com/docs/sales/pipeline/)
- [Moving a deal from stage to stage, end to end](https://connectbyjbrh.com/docs/workflows/move-opportunity/)
- [From an email to an opportunity](https://connectbyjbrh.com/docs/workflows/email-to-opportunity/)
- [Follow-ups on a deal](https://connectbyjbrh.com/docs/sales/sales-follow-ups/)
- [Customer 360](https://connectbyjbrh.com/docs/relationships/customer-360/)

## What this page is based on

- docs-source/sources/CHANNELS.md §6 and §7 — sales verbs, money and follow-up duplicates
- docs-source/sources/GENERAL.md §5 and §8 — autonomy, the audit trail and Assistant tools
- Connect capability registry (docs-source/facts.py)