Documentation Index
Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
Use this file to discover all available pages before exploring further.
This guide helps you decide when to keep a business process as one assignment and when to split it across multiple, and how to wire the hand-offs between them so work flows cleanly from stage to stage.
When to Keep It One Assignment
A single assignment is the right choice when the process fits these conditions:
- One coherent SOP. All steps belong to one logical flow that a single person would carry out end-to-end.
- One primary operator persona. The human approval steps all go to the same role — a single assignment handles its own exceptions.
- One integration cluster. The required connections belong to the same system or domain (for example, all Gmail + Google Sheets, or all Salesforce + Slack).
- Short end-to-end latency. The work completes in under five minutes with no waiting stages that could block downstream work.
If your process fails any of these checks, splitting it will make it more maintainable, reliable, and easier to reason about.
When to Split — and Which Seam to Use
Three conditions consistently warrant splitting into multiple assignments:
-
Different personas handle different stages. If the first stage requires a procurement manager to approve and the second stage requires a finance analyst to validate, keep the stages in separate assignments so each persona manages their own exceptions.
-
Different SLAs. High-priority intake should not be slowed down waiting for a batch of low-priority items to clear. Splitting lets each assignment run on its own schedule.
-
Reusable subroutines. If five assignments all need to “look up a customer record and validate their account status,” extract that step into one specialist assignment that the others can hand to.
Once you’ve decided to split, pick the seam based on the hand-off shape:
| Hand-off shape | Use this |
|---|
| One assignment produces items; another processes them asynchronously | Case Queue (producer/consumer) |
| A running assignment needs to escalate or route to a specialist right now | Assignment Handover |
| Multiple assignments share a reusable step | Assignment Handover from each caller |
Three Canonical Patterns
Pattern 1: Pipeline (A → B → C)
Each assignment adds context and passes the result to the next stage. Use the Case Queue producer/consumer seam.
When it fits:
- Intake, enrichment, and action are conceptually distinct stages
- Each stage has its own SOP author and approval chain
- Stages run at different speeds (intake is fast; enrichment is slow)
When it doesn’t fit:
- The stages are so tightly coupled that they share state in ways the queue data model can’t represent cleanly
- Total end-to-end latency matters more than separation of concerns
How to set it up:
- Stage A — the producer — runs on a trigger (email, webhook, schedule). Its SOP extracts the raw data and adds a case to the queue with the structured fields Stage B needs.
- Stage B — the first consumer — picks up Pending cases, enriches them, and adds enriched cases to a second queue for Stage C.
- Stage C — the final consumer — takes the enriched data and performs the write action (update the ERP, send the email, post the Slack message).
SOP snippet for Stage A (producer):
For each new order email:
1. Extract order number, customer ID, SKU list, and requested quantity.
2. If any required field is missing, flag the email for manual review
and stop — do not add a case.
3. Add a case to the "Order Intake" queue with title "Order [order number]"
and the extracted fields as data.
Pattern 2: Fan-Out (A → N parallel B’s)
One assignment identifies a batch of items and hands each one to a consumer that processes them in parallel.
When it fits:
- A large batch arrives on a schedule (end-of-day, end-of-week) and each item can be processed independently
- The items share the same SOP but contain different data
- Throughput matters — sequential processing would take too long
When it doesn’t fit:
- Items within a batch depend on each other (process item 1 before item 2)
- The write destination has strict rate limits and parallel consumers would breach them
How to set it up:
- Producer assignment — runs on a schedule or trigger. Queries the source system (database, spreadsheet, API), identifies all items to process, and adds one case per item to the queue.
- Consumer assignment — has the case trigger enabled with concurrency set to the appropriate parallel limit. Each case runs its own Job independently.
SOP snippet for the producer:
Run every weekday at 07:00.
1. Query Snowflake for all invoices with status "Pending" and due date today
or earlier.
2. For each invoice, add a case to the "Invoice Processing" queue.
Title: "Invoice [invoice_id] — [vendor_name]"
Data: invoice_id, vendor_name, amount, due_date, bank_details.
3. If the query returns more than 200 invoices, stop and request approval
before adding cases — this may indicate a data issue.
Pattern 3: Escalation (A handles routine, hands to B for exceptions)
One assignment covers the standard path. When a case falls outside the standard, it hands off to a specialist assignment rather than failing or requesting a generic HITL.
When it fits:
- A large volume of cases follow a predictable pattern but a small percentage require specialist judgment
- The specialist assignment has access to different connections or a different SOP
- You want clean separation between routine volume and exception handling
When it doesn’t fit:
- The majority of cases are exceptions — this pattern breaks down if the “routine” path is not actually routine
- The specialist assignment and the routine assignment are maintained by the same person — in that case, a single assignment with HITL is simpler
How to set it up:
- Triage assignment — processes all incoming cases. For routine cases, completes the action directly. For exceptions, requests a handover to the specialist assignment.
- Specialist assignment — configured as an allowed handover target. Its SOP handles the narrow class of edge cases the triage assignment escalates.
See Assignment Handover for step-by-step setup instructions.
SOP snippet for the triage assignment:
Process each customer complaint case:
1. Read the case data and classify the complaint as Billing, Technical,
or Policy.
2. For Billing complaints: look up the customer's account. If the disputed
amount is under $200 and the account is in good standing, issue the
credit and complete the case.
3. For Billing complaints over $200, or for accounts flagged for review:
hand over to @Billing Specialist with a note explaining the issue.
4. For Technical complaints: create a support ticket and complete the case.
5. For Policy complaints: hand over to @Policy Review.
Lineage and Traceability
When a source event travels through two or three assignments, you need to be able to follow it from end to end. Two practices make this reliable:
Passing a correlation ID
Include a unique identifier for the originating event in every case you add to the queue. Use the same field name across all stages.
Add the case with:
- title: "Order [order_id]"
- data.order_id: [the original order ID from the email]
- data.source_email_id: [the Gmail message ID]
Reading the case timeline
When a case passes through multiple assignments via Handover, the case detail view shows the full timeline: which assignment handled each stage, when it started, and what it did. Open a case in your queue and scroll to the timeline to see the complete processing history.
For jobs in the Jobs list, the job output for each stage includes the case ID so you can link stages together.
Anti-Patterns
| Anti-pattern | Why it causes problems | What to do instead |
|---|
| One mega-assignment that handles intake, enrichment, action, exception routing, and reporting | Nobody can safely edit it; one SOP change affects every path; test coverage is impossible | Split along the seams above; start with the natural persona or SLA boundaries |
| Two assignments that should be one | Adds latency, creates brittle queue serialisation for steps that share tight state, costs more to operate | Merge if they have the same SOP author, same operator, and complete in under five minutes |
| Circular handovers — A hands to B, B hands back to A | Creates infinite loops unless both SOPs have explicit termination conditions | Add a handover_count field to case data; instruct each assignment to stop if the count exceeds a threshold |
| Producer faster than consumer | Cases pile up in Pending; queue grows unbounded | Add concurrency to the consumer, or add a cap in the producer’s SOP (e.g., “add at most 100 cases per run”) |
| Implicit failure — an assignment ends without completing, postponing, or handing over the case | The case silently lands in Failed; no one knows what happened | Every assignment that consumes cases must explicitly complete, postpone, fail with a reason, or hand over |
Worked Example: Complaint Triage
This example shows how to take a Clarity-generated process and split it across three assignments.
The Clarity output
A Clarity session captured the following steps for handling inbound customer complaints:
- Read the incoming email
- Classify: Billing, Technical, or Escalation
- For Billing: look up account, issue credit if under $200, else forward to billing team
- For Technical: create a support ticket, assign to on-call engineer
- For Escalation: forward to account manager with a summary
The decomposition decision
| Step | Assignment | Reason |
|---|
| Steps 1–2 (intake + classify) | Triage | Runs continuously on an email trigger; needs access to Gmail only |
| Step 3 (billing resolution) | Billing Specialist | Needs CRM access and billing system access; different operator persona; low volume |
| Step 4 (technical ticket) | Triage | Simple action; same connections; no specialist judgment needed |
| Step 5 (escalation) | Account Manager Briefing | Different SLA (same-day); needs CRM + Slack; different recipient |
The wiring
- Triage consumes from the “Customer Complaints” queue (case trigger enabled).
- Triage uses Assignment Handover to route to @Billing Specialist or @Account Manager Briefing when the case falls outside its path.
- Billing Specialist and Account Manager Briefing are each configured with “Case Queue (Consumer)” so they appear as valid handover targets.
Lineage
Each case in the “Customer Complaints” queue carries data.source_email_id from the originating Gmail message. When a case passes through Handover to the Billing Specialist, the case timeline shows both stages. The Billing Specialist’s SOP includes the original email ID in any CRM record it creates, so the audit trail runs from inbox to CRM record.
