# Anatomy of a playbook

> What each field is for, how the classifier and the investigator use them differently, and how to tell a good playbook from a bad one.

Source: https://triagic.com/docs/playbooks

A playbook is a triage profile: *this kind of ticket, investigated this way, using
these systems.* It's the most important thing an admin configures, because it's the
difference between an agent that wanders and an agent that knows where to look.

For the mechanics of the editor, see [Managing playbooks](/docs/admin/playbooks). This
page is about what to put in it.

## Two consumers, four fields [#two-consumers-four-fields]

The fields are read by two different things at two different times, and confusing them
is the most common mistake.

| Field                   | Read by                 | When                                                    |
| ----------------------- | ----------------------- | ------------------------------------------------------- |
| **Description**         | The classifier          | At ingest, to decide which playbook a ticket belongs to |
| **Routing hints**       | The classifier          | Same                                                    |
| **Triage instructions** | The investigating agent | During the investigation, appended to its system prompt |
| **Data sources**        | The tool layer          | Throughout (it's the allowlist)                         |

So: **description and routing hints answer "is this ticket mine?"** and **triage
instructions answer "now that it is mine, what do I do?"**. Writing investigation
procedure into the description makes classification worse and does not help the agent
at all.

### Description [#description]

One or two sentences describing the *class of ticket*, in the language your customers
use, not your internal jargon.

> Tickets about money owed to a merchant that has not arrived: payouts, settlement
> timing, missing transfers, payout account setup.

Avoid writing what you would like to be true ("all payment issues"). The classifier
compares tickets against every playbook, and a vague description drags in tickets that
belong elsewhere.

### Routing hints [#routing-hints]

The keyword layer. Merchant names, product names, error strings your customers paste,
example subject lines.

> payout, settlement, transfer, "money not received", "where is my money", bank
> account, ACH, "payout pending"

This is where you put the phrasings that a semantic description misses: a specific
error code, an internal product codename customers have learned.

### Triage instructions [#triage-instructions]

The important field, and the only required one. This is a procedure written for
someone competent who does not know your systems.

See [Writing triage instructions](/docs/playbooks/writing-instructions). It's worth
its own page.

### Data sources [#data-sources]

The allowlist of MCP servers the agent may call. Selecting none means **all**, which
is a fine starting point.

Narrowing it makes investigations faster and cheaper and stops the agent drifting into
irrelevant systems. It also means a root cause living outside the allowlist becomes
unreachable, and the agent will correctly say so rather than inventing something.

## Visibility [#visibility]

Organization-wide, or restricted to selected teams. Team scoping governs who can
manually *use* the playbook. It does **not** govern auto-classification, which
considers every enabled playbook in the organization.

## Drafting one from a prompt [#drafting-one-from-a-prompt]

You don't have to start from a blank form. In the desktop app, an admin can press
**Generate from a prompt** on the **Playbooks** page, describe the class of ticket,
and pick what the AI may read: data sources, past tickets, existing knowledge docs.
It drafts all four fields from what it finds. Choose **Both, linked** to get a
knowledge doc as well, with the playbook's first step reading that doc.

The draft is private to you until you publish it. Ask for changes in plain words and
each changed field comes back as a redline you keep or discard. Publishing is free;
the drafting and revising runs show their price before you start them. Hold the
draft to the same standard as one you wrote yourself: the rest of this page applies
to it unchanged. Details in
[Managing playbooks](/docs/admin/playbooks#generate-a-playbook-from-a-prompt).

## How to tell whether a playbook is good [#how-to-tell-whether-a-playbook-is-good]

Run the same ticket twice.

1. **Scoped to this playbook**, and
2. **with no playbook at all.**

Compare the tool chips and the conclusion.

* Same answer, fewer tool calls → the playbook is doing its job.
* Same answer, same number of calls → the instructions are not adding anything yet.
* Worse answer → the data-source allowlist is too narrow, or the instructions are
  pointing at the wrong place first.

Then check the routing: filter the inbox by "no playbook" and see which tickets should
have matched. Those are your missing routing hints.

## Anti-patterns [#anti-patterns]

**One giant playbook.** If your allowlist is everything and your instructions are
"investigate the issue", you have a generic triage with extra steps. Generic triage is
already the default for unmatched tickets.

**Playbooks that overlap.** Two playbooks whose descriptions both plausibly match the
same ticket make classification a coin flip. Merge them, or sharpen both descriptions
until the boundary is obvious.

**Scoping away the answer.** A playbook that excludes the system where the root cause
actually lives produces confident "could not determine" reports forever. This is why
the two-run comparison above matters.

**Instructions written for a model rather than a person.** "You are an expert support
engineer" adds nothing. "Check `payout_configs` for a row matching the merchant before
anything else" adds everything.

## The five examples [#the-five-examples]

The following pages are complete, copyable playbooks covering the common support-ops
territory. If you would rather start from a draft of your *own* systems than from an
example, [generate one from your codebase](/docs/playbooks/generate-with-ai): a
single prompt you paste into whatever AI coding agent you use. They assume the data sources are named as in
[the integration catalog](/docs/integrations); adjust the keys to
match your own.

- [Payments & Payouts](/docs/playbooks/payments-and-payouts)
- [Checkout & Orders](/docs/playbooks/checkout-and-orders)
- [Catalog & Sync](/docs/playbooks/catalog-and-sync)
- [Platform Reliability](/docs/playbooks/platform-reliability)
- [Accounts & Sessions](/docs/playbooks/accounts-and-sessions)