# Writing triage instructions

> The one field that decides whether an investigation is good, and a structure that reliably works.

Source: https://triagic.com/docs/playbooks/writing-instructions

Triage instructions are appended to the investigating agent's system prompt for every
ticket on the playbook, and for its follow-up chats. This is where your team's actual
knowledge goes.

Write for a **competent new hire who does not know your systems**. Not for a model.

You do not have to start from a blank field: an AI coding agent with your repository
open can [draft the whole playbook](/docs/playbooks/generate-with-ai). The structure
below is what you'll be reviewing and editing either way.

## A structure that works [#a-structure-that-works]

### Say what these tickets are actually about [#say-what-these-tickets-are-actually-about]

One line of orientation. The agent already knows the ticket text; what it lacks is
your domain.

> A payout is a scheduled transfer of settled funds to a merchant's bank account.
> Merchants report "missing payouts" when the payout never generated, when it
> generated but was held, or when it sent and their bank has not posted it yet. These
> are three different problems.

### Give an ordered checklist [#give-an-ordered-checklist]

Ordering is the single most valuable thing you can contribute, because it is what
turns twelve tool calls into four.

> 1. `payout_configs`: does a row exist for this merchant? No row is the most common
>    cause and it is cheap to check.
> 2. If the row exists, check `bank_verified`. `false` holds every payout silently.
> 3. `payouts` for the period: did one generate at all, and what is its status?
> 4. Only then look at logs and errors for the send attempt.

### Name the tables, indices, metrics and labels [#name-the-tables-indices-metrics-and-labels]

Exact identifiers. This is what stops the agent guessing at schema.

> Payout state lives in Postgres: `payout_configs`, `payouts`, `payout_attempts`.
> Logs are in the `app-payments-*` OpenSearch indices; filter on `merchant_id`.

### List the known failure modes [#list-the-known-failure-modes]

Your accumulated institutional knowledge, and the highest-value part of the whole
field.

> Known causes, most to least common: missing `payout_configs` row; `bank_verified =
> false` after a bank change; payout below the merchant's minimum threshold; a
> processor-side hold visible only as a `payout.hold` event.

### Say what conclusions to reach and what to rule out [#say-what-conclusions-to-reach-and-what-to-rule-out]

> If a payout exists with status `sent` and a processor reference, the money has left.
> Say so explicitly and give the reference so support can point the merchant at their
> bank. Do not report "payouts are broken" when a single merchant's configuration is
> the cause.

### Say what to do when the answer is not there [#say-what-to-do-when-the-answer-is-not-there]

> If none of the above explains it, report exactly which of the four checks you
> completed and what each returned. Do not speculate about processor-side causes you
> could not observe.

## Rules of thumb [#rules-of-thumb]

**Be specific about identifiers, vague about nothing.** Every table name, index
pattern, metric name and label you can supply removes a round of guessing.

**Order matters more than completeness.** A three-step ordered checklist beats a
twenty-item unordered list, because the agent executes in order and stops when it has
an answer.

**Encode negative knowledge.** "Sentry errors from `checkout-worker` are noisy and
almost never the cause" is as useful as any positive instruction.

**Give it an out.** Explicitly authorizing "report what you could not determine"
produces honest reports instead of confident wrong ones.

**Do not restate the obvious.** The agent already knows it is investigating a support
ticket read-only. Persona preambles are wasted tokens on every single run.

## Length [#length]

Longer than you expect, shorter than a runbook. A good playbook's instructions are
typically 150–400 words: enough for orientation, an ordered checklist, identifiers and
failure modes, without turning into documentation the model has to wade through on
every call.

If yours is over a page, it is probably two playbooks.

## Iterating [#iterating]

Instructions are not write-once.

1. Read the tool chips on a few real investigations under the playbook.
2. Anywhere the agent checked something in the wrong order, or checked something
   irrelevant, that is a missing or mis-ordered line.
3. Every time an engineer finds a root cause the agent missed, add it to the known
   failure modes.

Each change reaches every desktop on the next sync. Existing tickets keep their old
report until re-investigated.