Playbook

---
name: playbook
description: Use whenever building, reviewing, fixing, or extending a SuperDialog voice-agent playbook YAML (the persona/llm/journeys/checkpoints/interrupts/policies/knowledge_base schema consumed by super/core/voice/livekit/lite_v2's PlaybookAgent/DialogMachine). Trigger on requests like "make a playbook for this agent", "build a YAML for [business] voice agent", "why is my agent hanging up / mixing up prices / answering the wrong program", "the caller's off-script question broke the flow", or any review of an existing playbook YAML — even if the user doesn't say "SuperDialog" or "playbook" by name, just describes a voice agent's booking/FAQ/pricing/routing behavior going wrong. Also trigger when asked to convert a raw client prompt/spec (a .txt persona doc) into this YAML format.
---

# Building a SuperDialog Playbook

A playbook is a Director+Talker voice-agent script: the **Director** (usually
a fast/cheap LLM) reads the transcript each turn and decides whether to
advance to a new checkpoint or fire an interrupt; the **Talker** (usually a
stronger LLM) speaks based on whatever checkpoint the Director landed on.
Almost every hard bug in a playbook traces back to one specific thing being
left to Director/Talker *judgment* when it should have been made
*structural* — a real slot, a real `judge: expr` rule, or a real code-side
guard. This skill exists because that lesson kept getting relearned the hard
way across three production playbooks — a slot-booking agent, a high-value-item
sales agent, and a programme-enrolment agent — before it got written down here.

That claim now has a number behind it. A later campaign against two of those
playbooks — 5 production incident traces, 3 ratified call transcripts, ~20 live
eval runs with assertions grounded in real API payloads — produced ~45 fixes.
Split by mechanism: deterministic renders, deterministic guards, routing
completeness and *deleting* example values from instructions held every time.
Prose rules of the form "never invent a price" went **0 for 8**, twice being
violated in the same paragraph that forbade the behaviour. Reach for prose last;
if a number matters, the engine must speak it. See `references/grounding.md`.

## Before writing anything: read the real schema

Don't guess field names. Read `references/schema.md` — it's the actual
`superdialog.playbook.models` Pydantic schema (persona, llm, journeys,
checkpoints, slots, advance_when, interrupts, policies, knowledge_base), not
a remembered approximation. Every field there was confirmed against the
installed library, not assumed from a prior example.

The four references, and when each earns its read:

| file | read it when |
|------|--------------|
| `references/schema.md` | always, before writing any field |
| `references/checklist.md` | drafting, and again as a review pass — 15 structural failure patterns |
| `references/grounding.md` | the agent speaks any number or asserts any fact — 12 grounding patterns |
| `references/interrupt-guard-pattern.md` | an interrupt misfires on a short in-flow reply |

## Workflow

1. **Source hygiene check, before anything else.** If you're compiling from
   a client-provided prompt/spec, skim the whole thing first for content
   that doesn't belong — a copy-pasted section from a *different* client's
   script is a real, recurring failure mode — one client's "off-topic
   termination" block once ended up wholesale inside a different client's
   prompt, for an unrelated line of business. If you build straight off a
   contaminated source, the agent's own scope rule ends up rejecting its real
   business as "off-topic." Flag
   anything that doesn't match the stated brand and confirm before
   compiling — don't silently paper over it or silently compile it as-is.

2. **Map the flow as a graph before writing YAML.** List the checkpoints and
   how they connect — greeting → routing → leaf topics → closing — on paper
   or in your head first. A playbook that's really a flat FAQ/pricing lookup
   with light routing wants a hub-and-spoke shape: one small checkpoint per
   topic, a dedicated routing checkpoint in the middle, not one giant
   persona block trying to hold every topic at once. See pattern 5 in the
   checklist for why the giant-block version breaks.

3. **Draft the checkpoints, slots, and interrupts**, using
   `references/checklist.md` as you go — it's organized as 15 concrete
   failure patterns, each with the root cause and the fix, not just a bare
   rule list. Read the *why* for each one you apply; the fixes generalize
   badly if copied mechanically without understanding what they're actually
   preventing.

4. **Before shipping, walk the checklist as a review pass**, not just while
   drafting. It's easy to get a checkpoint's happy path right and miss that
   its failure path (turn_budget exhausted, tool call failed, ambiguous
   input) has nowhere safe to go.

5. **If the agent speaks any number — a price, a fee, a date, a slot time,
   a quantity — read `references/grounding.md` before shipping.** It's 12
   patterns covering the class that survives a structurally perfect playbook:
   the agent stating a figure nothing in the system produced. Two checks pay
   for themselves immediately: every `{{ name }}` in guidance /
   `say_verbatim` / tool templates must resolve to a declared slot,
   `results.*` key or `env` entry (three live playbooks had references that
   resolved nowhere and rendered blank on *every* traversal — the model
   filled the blank); and no instruction anywhere may contain an example
   value the agent could speak as real data (five separate incidents traced
   to exactly that).

6. **If the bug being fixed is an interrupt misfiring on a short in-flow
   reply** (a bare "no"/"nothing" getting classified as a call-ending
   goodbye), know up front that this can't be fully fixed in YAML alone —
   `InterruptSpec.judge` is `llm | event` only, there is no `expr` option at
   the interrupt layer. Defensive `when:` wording helps but has been
   observed to still misfire under a fast/cheap Director model. The pattern
   that actually held in production is a small host-side code guard — see
   `references/interrupt-guard-pattern.md` for the exact shape (it's a
   ~20-line pure function, not a rewrite).

## A pattern, not a rule, on Director model choice

If a playbook leans heavily on disambiguation (which program did they mean),
compliance (never skip the disclaimer line), or the interrupt-misfire class
of bug above, the Director's own model quality matters more than its
latency. A fast/cheap model tuned for low latency has been observed
misclassifying exactly this kind of nuanced turn, repeatedly, even with
explicit examples in the prompt. Don't default the Director to "whatever's
fastest" for a playbook like this — a stronger small model (e.g. Claude
Haiku-class) at the Director role is usually worth the few hundred extra
milliseconds.

## Worked example

A playbook built for a programme-enrolment voice agent applied most of the
checklist proactively, from a first draft — deterministic programme-name
disambiguation, `say_verbatim` compliance lines, a scoped `knowledge_base` +
`uses_kb` split by checkpoint, defensively-worded interrupts from the start
rather than retrofitted after a misfire, and a stronger Director model. It's
the reference point for "apply the checklist up front," not just "fix it
after it breaks in production" — both are valid uses of this skill, but
proactive is cheaper than a postmortem.