# Moving a deal from stage to stage, end to end

A move is a claim about the deal, so it is checked before it is written. `move` evaluates the stage rules, either declines with the specific thing that is missing or writes the new stage, audits the change, and raises whatever the new stage implies — usually a dated commitment with a reason attached.

- **Status:** Available
- **Audience:** both
- **In the app:** #/pipeline, #/follow-ups, #/needs-you
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/move-opportunity/

## The stages of a stage change

1. Trigger — somebody drags a card, edits the deals sheet, or asks the Assistant to advance the deal.
2. User or external event — nothing external happens; this is an internal decision about a record you already hold.
3. Authentication and workspace resolution — the workspace is entered first, so the rules are evaluated against your deal and not against a row that merely shares an identifier.
4. Ingest or request — `move` is called with the target, from whichever surface asked. All three surfaces call the same one.
5. Canonical record — nothing is written yet. The deal is read as it currently stands, including value, counterparty and any review flag.
6. Reasoning — the stage rules are evaluated: ordering, the evidence the target stage assumes, authority over commercial terms, and whether the target is terminal.
7. Knowledge, memory and rules — where the move depends on a commercial term, only a grounded one counts; an invented figure is refused rather than accepted as evidence.
8. Autonomy and approval — the move itself needs no approval. If the missing piece is a decision, `raise_for_review` puts the deal in Needs You instead of forcing it through.
9. Action through a provider — none for the move. Any message the new stage implies goes out separately, under its channel's autonomy.
10. Result — the stage is written and the card sits in its new column, or the move is declined and the card does not move at all.
11. Relationship, timeline and memory — the change appears on the person's timeline, so the relationship shows commercial progress next to conversations.
12. Audit, usage and Needs You — the decision log records what moved, who moved it and under which rule, including refusals, because a refusal is a decision.

## What each outcome does

| Outcome | What you see | What changes | What can fail |
|---|---|---|---|
| Permitted | The card in the new column | The stage, plus anything the stage implies | The implied commitment is created without a reason, which makes it useless later |
| Declined | The card back where it was, with the missing thing named | Nothing at all | Reading the refusal as a fault and re-trying from another surface, which gives the same answer |
| Raised for review | The deal marked as waiting, and an item in Needs You | A review flag, cleared later by `clear_review` | Nobody watching the queue, so the deal waits on a person who does not know |
| Terminal | A closed outcome with its reason | The deal leaves the working board | Commitments left open behind it — walk the queue |

> **Note** Every surface calls the same `move`. The board, the deals sheet in `#/data` and the Assistant are three ways to ask, not three sets of rules, so a rule that declined one declines all three.

## The side effects worth knowing about

**A new commitment** — Most forward moves imply a next contact. It arrives in the follow-up queue with a channel and a reason; identical timing for the same person is treated as one row.
**A demo, where the stage is about one** — Requesting, scheduling, completing and cancelling a demo are their own verbs, because a demo is a commitment with a time rather than a state of mind.
**A changed recommendation** — The next best action reads the stage, so advancing a deal changes what is suggested next — usually within the same view.
**Nothing said to the customer** — A stage change is internal. If the customer should hear something, that is a message and it passes the ordinary gates.

## Retries, ordering and what is safe to repeat

- A declined move writes nothing, so repeating it is harmless and equally useless until the missing thing is supplied.
- A permitted move applied twice is the same stage twice: the second is a no-op on the record but still an audit entry, which is the honest way round.
- Moves are not reordered. A deal that skipped a stage did so because the ordering rule allowed it, not because two requests raced.
- Reopening a closed deal is an ordinary move subject to the same rules, and it is deliberate rather than accidental.

> **Careful** If a move succeeds on the grid and fails on the board, that is a defect worth reporting rather than a workaround worth using. One service owns the rule; two answers means something is wrong.

## Proving the move did what you wanted

1. Check the column and the card's value together.
   - Result: A move that changed the stage and lost the value is visible immediately and nowhere else.
2. Open the follow-up queue for that person.
   - Result: The implied commitment is there with a reason, or it is not — and a missing next action is the most common quiet failure of a forward move.
3. Read the timeline entry.
   - Result: Commercial progress reads in sequence with the conversations that caused it, which is what makes a handover to a colleague possible.
4. Read the decision log entry, especially after a refusal.
   - Result: It names the rule, which is the difference between 'the board is broken' and 'this deal needs a figure nobody has agreed'.

## Questions

### Can I move several deals at once?

The deals sheet in `#/data` supports bulk actions, and each row goes through the same service and the same rules. Expect some rows to be declined while others succeed — that is the rules working per deal, not a partial failure.

### Does a backward move undo the previous stage's side effects?

No. A commitment created when the deal advanced is a real promise to a real person, and moving the card back does not unpromise it. Cancel it deliberately if it no longer applies.

### Why did the Assistant refuse to advance a deal I can advance myself?

Check what it reported. Where the blocker is a commercial term, the Assistant may not decide one — that is the same authority boundary that stops it quoting a price, and you deciding is the intended path.

## Related

- [Stage rules and refusals](https://connectbyjbrh.com/docs/sales/stage-rules/)
- [The pipeline board](https://connectbyjbrh.com/docs/sales/pipeline/)
- [Creating an opportunity, end to end](https://connectbyjbrh.com/docs/workflows/create-opportunity/)
- [Closing a deal: won and lost](https://connectbyjbrh.com/docs/sales/won-and-lost/)
- [The deal would not move stage](https://connectbyjbrh.com/docs/troubleshooting/stage-move-refused/)
- [The next best action on a deal](https://connectbyjbrh.com/docs/sales/next-best-action/)

## What this page is based on

- docs-source/sources/CHANNELS.md §6 and §7 — move, demos and follow-up duplicates
- docs-source/sources/GENERAL.md §5 and §9 — the audit trail and the data grid
- Connect capability registry (docs-source/facts.py)