> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudsquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SOPs: teaching the agent your process

> Your standard operating procedure as a Markdown file the agent follows — readable, diffable, approvable, and written together with the agent.

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](/concepts/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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Tolerances, stated numerically">
    "Amount may differ by up to 2% or €10, whichever is smaller" is a rule. "Roughly the same" is not.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Worked examples">
    One or two real cases with the expected outcome. Examples resolve ambiguity that prose can't.
  </Step>
</Steps>

### A concrete fragment

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

```md theme={null}
## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Your process expert answers">
    Not an engineer — the person who actually knows the process. They answer in the chat; the agent revises the file.
  </Step>

  <Step title="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. {/* ⚠️ VERIFY: whether the stamp is a file convention or platform-tracked. */}
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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](/concepts/projects).

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](/concepts/tables), sharing this file.

<CardGroup cols={2}>
  <Card title="The improvement loop" icon="arrows-spin" href="/concepts/improvement-loop">
    How review feedback turns into SOP revisions.
  </Card>

  <Card title="A complete starter SOP" icon="book-open" href="/cookbooks/po-matching">
    The PO matching cookbook ships a full, copy-paste SOP.
  </Card>

  <Card title="Review & approvals" icon="user-check" href="/concepts/review-approvals">
    Where the SOP's stop-and-escalate rules show up.
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/concepts/skills">
    Reusable capabilities, as opposed to this process's rules.
  </Card>
</CardGroup>