Modelling a process as a Storyline — the right way

Turning a complex process into a Storyline is a modelling exercise, not a transcription. The mechanics are in Compile a flow into a Storyline; this is how to think about it so the result is reliable rather than a graph that mostly works.

Start from the profile, then the decision points

Before drawing nodes, decide what you are tracking — that is the profile_schema (e.g. docs_ready, risk_flag, attempts). Then map the real decision points, not just the happy path. Every place the conversation can branch or fail is a node with exits; a flow that only models the ideal path breaks the first time a user does something unexpected.

One node = one coherent step

A node should do one thing a person would name ("collect documents", "confirm identity"). Don't cram a whole sub-process into a single node's task and hope the model sequences it — you lose the ability to branch, resume and measure. If a node's task has "and then, and then", it's several nodes.

Make branching deterministic where the outcome must be reliable

• Route on rule (against profile dims) or user_choice when the branch must be predictable. Reserve ai exits for real judgment ("did they actually describe their problem?").
• Exits are priority-ordered — put the deterministic ones first, the ai fallback last.
• Model a retry loop with a back-edge plus a writes counter (op: "inc") and a rule cap. Never rely on the model to decide it has looped enough.

Keep identity and safety on the agent, not the node

The agent's soul and safety boundary are constant across the whole Storyline — that is the point. Don't try to re-state the persona or re-impose safety per node; nodes only add task/skills/kb/tools and write profile dims.

Keep node_keys stable; validate before publish

node_keys are the identity exits and the funnel reference. When you edit with update_storyline, keep them stable — renaming a node silently orphans its exits. Always validate_storyline before publish_storyline; it catches unreachable nodes, dead ends and dangling exits.

Don't over-model

If the task is a single question and answer, it is not a Storyline — it's an agent with a knowledge base. Reach for a Storyline when there is genuine multi-step state to carry (intake, tutoring, a guided application). Modelling a one-shot Q&A as a graph adds cost and failure modes for nothing.

Common ways it goes wrong (avoid these)

• Happy-path only — no exit for "user is confused" or "didn't provide it", so the flow stalls.
• Everything is an ai exit — routing becomes a gamble; the same input takes different paths.
• A mega-node — one node's task describes the entire process; nothing can branch or resume.
• Unbounded loops — a back-edge with no counter and no cap.
• Restating safety per node — noise that competes with the agent's actual boundary.

Fix these by naming the real states and moving each decision onto a deterministic exit.