Moving a relationship through its lifecycle

What a stage is for#

It is the single field the rest of the workspace reads to know who somebody is now. A prospect and a client asking an identical question deserve different answers; research should not spend money discovering an organisation that has been a customer for a year; a next-best-action for somebody mid-onboarding is not the one for somebody mid-negotiation. All of that keys off the stage.

Which is why it is deliberately a recorded decision rather than something derived. A field that drifted on its own — promoted by a warm reply, demoted by a quiet month — would be a field nobody could safely build on, and everything above would quietly become unreliable at the same time.

The stage chain#

1. Trigger — something makes the current stage untrue: a deal closes, a prospect replies for the first time, onboarding finishes, a customer leaves.
2. User event — a person moves the stage on the relationship, or asks the Assistant to, which reaches the same service through set_lifecycle_stage.
3. Authentication and workspace resolution — the workspace is fixed first; a stage can only be set on a person who belongs to it.
4. Ingest — the request carries the person and the requested stage as a word.
5. Canonical record — the Person. The stage is a field on that record, not a folder the person is moved into, which is what makes it correctable rather than a migration.
6. Classification — the requested word is normalised against the workspace's own vocabulary, supplied by stages(). Free text that means the same thing lands on the same stage; a word that means nothing is not quietly accepted.
7. Knowledge, memory and rules — none of them override this. Memory records what Connect knows about a person; it does not decide what stage they are in.
8. Autonomy and approval — permission to change a record is not permission to send anything. Moving a stage sends nothing, so no send-side approval is involved.
9. Action — move_stage writes the new value. journey.py owns lifecycle stages, so the same call serves the operator's screens and a customer's.
10. Result — the field holds the new stage. Everything that reads stage sees the change immediately; nothing else about the relationship moves with it.
11. Relationship and timeline — the change appears on the person's timeline in the order it happened, so the history explains itself later without anybody remembering.
12. Audit — who moved it, when, and to what. That is what turns 'they were marked a client in March' from an argument into a record.

What a stage change does not do#

Where it goes wrong#

Two records, two stages

The same human is a prospect on one record and a client on another, so half the workspace treats them as new. Merge them; both sides' stages, identities, follow-ups, deals, cases and onboarding survive.

A stage that was never moved

Nothing derives it, so a customer who bought six months ago can still read as a prospect. Everything downstream will behave accordingly, correctly, on wrong information.

A word the vocabulary does not hold

Normalisation exists precisely so free text does not create a private stage nobody else reads. If a genuinely new stage is needed, it belongs in the vocabulary rather than in one record.

Moving stage instead of closing something

A won deal, a resolved case and a finished onboarding each have their own closing action. A stage change is not a substitute for any of them.

Questions#

Related#

• Lifecycle stages
• Normalising a stage
• The relationship after the sale
• Stage rules and refusals
• Deciding whether two records are one person
• The next best action on a deal