Writing briefs
The highest-leverage field in the product, four worked examples, and the failure modes of each.
A brief is what an agent is for, in sentences. It is not a prompt in the sense of a clever incantation, and it is not a specification. The useful test is whether a new starter could follow it without asking a follow-up question — and the reason briefs fail is almost never that they are too short, it is that they describe only the happy path.
The four parts
- The job
- What this agent is responsible for, stated once. One job per agent; an agent with three jobs does all three worse than three agents would.
- The boundary
- Where the job stops. This is what stops an agent being helpful in a direction you did not ask for.
- When unsure
- What to do rather than guess. Without this an agent guesses, because guessing is the only option you left it.
- Never
- The short list of things that are wrong regardless of context. Keep it short; a list of twenty is a list nobody can hold.
Worked example — supplier chasing
Chase suppliers who are late against the delivery date on the
purchase order.
Chase once at three days late and once more at seven. Use the
supplier's own thread if one exists rather than starting a new one.
If a supplier gives a new date, put it on the item and stop chasing.
If a supplier disputes the order contents, hand off to a person and
do not negotiate.
Never agree to a price change. Never confirm a substitution.Worked example — inbound customer mail
Turn customer mail about orders into board items and draft the reply.
Attach the order reference where the message names one, or where the
address and the recent order list identify it beyond doubt. If it does
not, ask the customer for the order number rather than guessing.
Draft replies in the same register the customer used. Do not apologise
for delays that have not happened.
Anything about money — refund, discount, goodwill, replacement — is
drafted and routed to a person, never sent.
Never quote a delivery date the courier has not confirmed.Worked example — stock cover
Watch cover on the forty lines that sell most, recalculated from
actual sales rather than a fixed reorder point.
Raise an item when cover falls below twenty-one days, and again at
ten. Include the current rate of sale and the last supplier lead time.
If the sheet and the listing disagree on quantity, raise it as a
reconciliation item and do not reorder against either number.
Never place an order. Draft it and route it.Worked example — returns triage
Sort inbound returns into: damaged in transit, not as described,
changed mind, and outside the window.
Ask for a photograph where the customer says damaged and has not sent
one. One request, not two.
Changed-mind returns inside the window follow the standard process.
Everything else goes to a person with the evidence attached.
Never tell a customer a return is approved. Never tell one it is
refused.How briefs fail
| Symptom | Usually means | Fix |
|---|---|---|
| Everything ends up handed off | The boundary is drawn tighter than the job | Widen the boundary, or narrow the job to match it |
| The agent is confidently wrong | No “when unsure” clause | Add one. It is the single most effective sentence in a brief |
| Triage keeps growing | The brief does not match what arrives | Read five triage items and write the brief for those |
| Two agents pick up the same item | Overlapping briefs | One job per agent; overlap is a briefing bug, not a scheduling one |
| Output drifts over weeks | The brief describes a goal, not a job | Replace the goal with the behaviour you want |