authoring-support-runbooks

Authoring Support Runbooks

Overview

A runbook is the pre-authored decision tree the runtime support agent follows for one user symptom: it says which checks to run (via the read-only tools), how to branch on the results, and where each branch ends. Runbooks are what make the runtime agent behave like a technician instead of a chatbot, and they are what let a weaker runtime model stay reliable — the judgement is authored here, in advance, so at runtime the model mostly selects among pre-authored branches rather than reasoning open-endedly.

This skill produces, for mandatory human review:

1. an intent taxonomy / router that maps an incoming user message to the right runbook;
2. one runbook (decision tree) per symptom;
3. a set of synthetic evaluation tickets that stand in for the real ticket history that does not exist yet.

Core principle: a runbook never invents a resolution. Every branch ends in one of exactly four outcomes, and every check it performs maps to a tool that already exists in the catalog.

The four terminal outcomes (every branch ends in one)

1. Self-serve — answer or instruct the user, grounded in specific knowledge-base articles.
2. Ask — request one clarifying detail, then re-enter the tree.
3. Escalate as unknown — out of scope or undiagnosable; hand to a human without guessing.
4. Escalate with a proposed fix — a change is warranted; emit a structured proposal (what change, on what entity, and why) for a human to approve and the privileged executor to perform. The agent proposes; it never performs the change and must never imply that it did.

Where runbooks come from (you have no real ticket history)

Because there is no historical ticket data, derive everything from the product itself:

• The failure surface — every error return, rejected input, and "entity in a bad state" branch in the backend is a symptom a user can report. Inventory these; each becomes a candidate runbook. (In a schema-blind setup, take these from the harness's plain-language conditions rather than from raw code.)
• The harness — supplies the plain-language description of each capability and its conditional behavior, and the articles that self-serve branches cite.
• The tool catalog — supplies the checks. Prefer the verdict-returning checkers; a runbook step should read a diagnosis, not raw data.