Handoffs between workflows

Real work crosses lines. QA finds a security problem in a feature: that is not a QA failure, and it is not the feature engineer's next task. It belongs to whoever does security. In CodeBook the workflows of a factory can hand cards to each other, so the Security workflow handles it and the card returns to Development.

Three ways to cross

	What happens to the card
Move the card	The card itself leaves this workflow and becomes the other one's. One card, one history, a new home.
Send and carry on	A linked card is opened in the other workflow. This one keeps going. A failed deploy opening an incident: nothing here waits for the postmortem.
Send and wait	A linked card is opened in the other workflow, and this one waits. When that one is finished, this card resumes — at the station it left, or at one you name.

Send and wait is the one in the example above: QA sends to Security and waits; when Security is done, the story comes back to Development.

Routing an outcome to another workflow

In a station's settings, under Then move the card, each of the three outcomes — passes, fails, blocked or out of retries — lists the columns of this workflow and then the stations of every other workflow in the factory. Pick a station in another workflow and the outcome becomes a route: choose how the card crosses and, for send and wait, where it resumes.

Handoffs an agent may choose

Sometimes the right destination is a judgement: most QA failures go back to Development, but this one is a security problem. Under Handoffs this agent may choose you list the routes the station's agent is allowed to take, each with a label saying when to use it — "Security issue found".

An agent can hand off along these routes and no others. The topology is yours and the system enforces it; it is not something a prompt asks for. A person, on the other hand, can send a card to any workflow in the factory from the card itself.

The brief

A handoff is not a bare move. It carries a typed brief:

• The goal — the outcome needed from the other workflow.
• The evidence — what was found.
• The open questions — what is not known yet.

The receiving workflow's first worker reads a specification, not a transcript, and starts from what is known rather than from a title.

What keeps it bounded

• Nothing leaves the factory. A card can only be handed to a workflow in its own factory.
• Loops are bounded. A chain of handoffs is traced back to the card that started it, and is limited in how deep and how wide it may grow. Two workflows that send to each other stop with a message a person can read, rather than forever.
• Links are kept. A sent card and the card that sent it stay linked, which is how a waiting card is found again when the other workflow finishes.
• A card that has moved on is not dragged back. If the waiting card was deleted or moved by a person in the meantime, the other workflow's card carries on with its own life.

Designing the routes

Route by who does the work, not by what went wrong. A route to Security exists because security specialists work that line, not because "security" is a kind of failure.

Prefer send and wait when the original work cannot finish without the answer. Prefer send and carry on when the other workflow's result does not change what happens here.

Keep a person at the far end. A workflow that receives handoffs should end the way every workflow should: with a station a person holds.