# How-to — goal → sequence → invariant

> Start here when someone asks **how to do a thing**, not why it broke. Each how-to takes one task
> in the operator's own words and gives you the call sequence that accomplishes it, the invariant
> that proves it worked, and the specific ways it fails silently.

The rest of `knowledge/` is organized by **capability** — what a trigger is, how the workflow engine
works, what the eight v5Config fields do. `runbooks/` is organized by **symptom**. Neither shape
answers "how do I set this up", which is what most questions actually are: a capability doc tells
you a feature exists without telling you the order to call things in, and a runbook only helps once
something is already broken. Without this layer the sequence gets re-derived from tool descriptions
every session, which is how a five-call task becomes twenty.

Not the same thing as the wiki's **[Production recipes](../../docs/wiki/en/recipes.md)**. Those are
pasteable prompts an operator sends to Claude. These are the procedures underneath — written for
whoever executes the calls.

## How to use one

1. Read the whole thing before starting. A sequence with a silent failure in step 3 is not
   something to discover at step 5.
2. Run the steps **in order**. Where the order matters, the doc says why — usually because a write
   deletes before it checks.
3. Check the invariant at the end. Most of these tasks succeed loudly and fail silently, so
   `{success: true}` is not verification.
4. Take the "don't" seriously. Several of these open by telling you the feature is probably the
   wrong tool. That is the most valuable line in the document, not a disclaimer.

## The set

| How-to | Covers |
|---|---|
| [`multi-agent-routing.md`](multi-agent-routing.md) | routing one inbox across several agents; comparing two prompts head to head |
| [`send-a-resource.md`](send-a-resource.md) | sending a link, an image or audio with the agent, or a PDF/document/video through a follow-up |
| [`test-before-launch.md`](test-before-launch.md) | exercising an agent against simulated leads before real ones arrive |

## Writing a new one

Keep the shape. A how-to that turns into a reference doc stops being followable.

```text
YOU WANT — how the question actually gets asked, ES + EN
THE HONEST ANSWER — if the feature is usually the wrong tool, say so before the steps
THE SEQUENCE — numbered, in execution order, one tool per step
THE INVARIANT — what must be true afterwards, and how to read it back
HOW IT GOES WRONG — the silent failures, each with what it looks like from outside
SEE ALSO — the neighbouring docs, including the one people land on by mistake
```

Rules that keep them honest:

- **Do not quote a doc's advertised phrasings in the table above.** Describe what it covers
  instead. The index repeating those strings makes this README compete with the docs it indexes —
  observed 2026-08 on this repo's own search: the index was winning the top slot on one doc's own
  phrase, and it gets worse with every doc added.

- **Lead with the recommendation, even when it is "don't".** Adoption data belongs at the top if it
  argues against the feature.
- **Every step is a real tool call**, named, with the argument that people get wrong.
- **Name what returns `{success: true}` and lies.** A silent failure the reader doesn't know about
  is the whole reason the doc exists.
- **Cite evidence by vertical and date, never by account.** These ship to clients in the published
  playbook — same rule as the runbooks.