Writing triage instructions

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

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.

A structure that works

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

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

payout_configs — does a row exist for this merchant? No row is the most common cause and it is cheap to check.

If the row exists, check bank_verified. false holds every payout silently.

payouts for the period — did one generate at all, and what is its status?

Only then look at logs and errors for the send attempt.

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

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

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

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

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.

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

Instructions are not write-once.

Read the tool chips on a few real investigations under the playbook.
Anywhere the agent checked something in the wrong order, or checked something irrelevant, that is a missing or mis-ordered line.
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.