SOPs: teaching the agent your process

An SOP is your process, written down. In cloudsquid it’s a Markdown file — SOP.md — in the project’s Files. The agent loads it and follows it on every case. That choice matters more than it looks. Because the procedure is a file:

Anyone can read it. Your controller can check what the agent will do without opening a config screen or learning a rule syntax.
Changes are diffable. “What changed after last month’s mismatch?” is answerable.
It’s approvable. A process change is a document change someone signed off on.
The agent can improve it. It reads your review comments and proposes revisions — see the improvement loop.

You are not configuring software. You are training a new team member, and the SOP is what you hand them.

Anatomy of a good SOP

A good SOP reads like something you’d hand a new hire on day one — specific, ordered, and explicit about when to stop.

Field mappings

Name the fields and where they come from. “The buyer’s VAT ID is on the order header, sometimes in the footer” saves the agent a guess on every case.

Ordered decision steps

Not “match the customer” but a sequence: try this, then this, then this. Order encodes priority, and priority is most of the judgment.

Tolerances, stated numerically

“Amount may differ by up to 2% or €10, whichever is smaller” is a rule. “Roughly the same” is not.

Explicit stop-and-escalate rules

The most valuable lines in the file. Say exactly when the agent must stop, flag, and list candidates instead of deciding.

Worked examples

One or two real cases with the expected outcome. Examples resolve ambiguity that prose can’t.

A concrete fragment

Here’s what a real match section looks like — from an order-matching SOP:

## Customer matching

### Step 1 — Name + address
Match the buyer block against `customer_master` on company name AND
postal code. Normalize before comparing:
- Strip legal-form suffixes: GmbH, AG, Ltd, B.V., S.p.A., Inc.
- Expand or strip umlauts both ways: ü ⇄ ue, ö ⇄ oe, ä ⇄ ae, ß ⇄ ss
- Ignore case, punctuation, and extra whitespace
- Treat "Str.", "Strasse", "Straße" as equivalent

A match on normalized name + postal code is a **confident match**.

### Step 2 — Email tiebreaker
If Step 1 returns more than one candidate, compare the sender address
and any contact email on the document against `customer_master.email`.
An exact email match resolves the tie. A domain-only match does not —
several sites of one group share a domain.

### Step 3 — Decide or flag
- Exactly one confident match → set `customer_number`,
  `match_status: matched`.
- Two or more candidates after Step 2 → set `match_status: ambiguous`,
  write the candidate customer numbers into `match_candidates`, and
  stop. Do not pick one.
- No candidate → set `match_status: unmatched` and note in the comment
  what you searched for. Do not create a customer.

**Never** invent a customer number. An unmatched order is a normal
outcome; a wrong customer number is a shipment to the wrong company.

Note what’s doing the work: the normalization list, the numbered order, and the last paragraph. That’s the difference between an agent that guesses and an agent you can trust.

The lifecycle: the agent drafts, you correct

You don’t write the first draft from a blank page.

The agent drafts from your real data

Point it at your master data and a handful of real documents and ask for an SOP. It reads them and proposes a procedure grounded in what’s actually in your files — the field names you use, the shapes your documents come in.

It flags what it can't know

A good draft ends with open questions: “Two customers share this address — how do you distinguish them?” “Do partial deliveries get one case or several?” These are exactly the questions a new hire would ask in week one.

Your process expert answers

Not an engineer — the person who actually knows the process. They answer in the chat; the agent revises the file.

The change is stamped and approved

The SOP carries a version stamp and the latest approver, so process changes stay reviewable. Keep both in a header line at the top of the file.

The open-questions step is where most of the value is. An agent that says “I don’t know how you handle this” is telling you where your process was ambiguous all along.

Editing by chat

You don’t have to hand-edit the file. Ask:

We’ve decided: express shipping to Austria always goes via road, never air. Update the SOP.

The agent edits SOP.md, explains what it changed, and — importantly — flags decisions it had to make on your behalf: “I put this under shipping resolution as a hard rule, above the customer default. Confirm that outranks a customer’s standing air preference.” Review that flag before you move on. It’s the agent showing its work on the one thing it couldn’t know.

SOPs vs. the Operating Procedures field

Two different things, easily confused:

	Operating Procedures (table setting)	`SOP.md` (file)
Where	The reconcile table’s Configure view	The project’s Files
Length	One or two lines	As long as the process needs
Contains	The standing instruction and a pointer	The actual procedure
Changes	Rarely	As the process is refined

Keep Operating Procedures to something like Match incoming orders according to the SOP. and put everything else in the file. A procedure buried in a text box isn’t reviewable, isn’t diffable, and can’t be improved by the loop.

One SOP per project

One project, one process, one SOP. It’s SOP.md, at the root of the project’s Files, and it’s what the agent loads and follows. This is a constraint worth keeping. One procedure per project means there’s never a question about which rules applied to a case. If you find yourself wanting a second SOP, you have a second process — give it its own project. Two things that are not exceptions to this:

Language copies. SOP.md and SOP_DE.md can sit side by side. That’s the same procedure in two languages so the team that owns it can read it in theirs — one process definition, two renderings. Not two SOPs.
Supporting documents. When a process gets big, don’t split the SOP — split the detail out of it. A routing table, a code list, a set of worked examples go in their own files alongside SOP.md, referenced from it so the agent knows to open them. The procedure stays in one place; the lookup material lives next to it.

Steps of one process aren’t separate SOPs either — they’re separate tasks in one reconcile table, sharing this file.

The improvement loop

How review feedback turns into SOP revisions.

A complete starter SOP

The PO matching cookbook ships a full, copy-paste SOP.

Review & approvals

Where the SOP’s stop-and-escalate rules show up.

Skills

Reusable capabilities, as opposed to this process’s rules.

Getting started

Core concepts

Cookbooks

More guides

SOPs: teaching the agent your process

Anatomy of a good SOP

A concrete fragment

The lifecycle: the agent drafts, you correct

Editing by chat

SOPs vs. the Operating Procedures field

One SOP per project

The improvement loop

A complete starter SOP

Review & approvals

Skills

​Anatomy of a good SOP

​A concrete fragment

​The lifecycle: the agent drafts, you correct

​Editing by chat

​SOPs vs. the Operating Procedures field

​One SOP per project

The improvement loop

A complete starter SOP

Review & approvals

Skills

Anatomy of a good SOP

A concrete fragment

The lifecycle: the agent drafts, you correct

Editing by chat

SOPs vs. the Operating Procedures field

One SOP per project