Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gainable.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
What is a playbook?

A playbook is the recipe an agent runs when an objective needs attention. It has three parts:
  1. A trigger. What starts the playbook. One of schedule, data change, webhook, or user-triggered.
  2. Steps. A sequence of tool calls, each one observed by the runtime and recorded in the action log.
  3. Guardrails. Constraints that bound the playbook: rate limits, scopes, risk tier, allowed recipients, max recursion.
Think of an objective as the “why” and the playbook as the “how.”

​
The shape of a playbook

name: Nudge stalled deals
trigger:
  type: schedule
  cron: "0 9 * * 1-5"
steps:
  - tool: query_collection
    collection: deals
    filter: "stage != 'closed' AND days_since_stage_changed_at >= 14"
  - tool: query_collection
    collection: contacts
    filter: "id IN {{ step1.deals[*].contact_id }}"
  - tool: draft_for_approval
    template: stalled_deal_followup
    recipient: "{{ step2.contact.email }}"
    owner: "{{ step1.deal.owner }}"
guardrails:
  scope: app_wide
  risk_tier: draft_and_approve
  rate_limit_per_user: "10/day"
  exclude_recipients_in: [unsubscribes, do_not_contact]
This pattern, trigger → steps → guardrails, is the same for every playbook in every Gainable app. Once you understand it, you understand all of them.

​
The playbook editor

Playbooks live in the Autopilot UI. The editor shows:
  • Trigger panel. Pick the trigger type and configure it.
  • Step list. Drag steps. Each step is a tool call. Inputs can reference previous step outputs.
  • Guardrails panel. Risk tier, rate limits, scopes, recipient exclusions.
  • Test panel. Run the playbook against test data without lighting up real recipients.
You don’t have to use the editor. Almost everything you can configure in it can be described in natural language during a build prompt. The editor is for fine-tuning after the fact.

​
”Simulate on last 30 days”

Before turning a playbook live, run Simulate on last 30 days. The runtime replays your real data through the playbook against the last 30 days of activity and shows:
  • How many times the trigger would have fired
  • How many drafts would have been produced
  • Per draft: the recipient, the message, the reasoning chain, the tool calls
  • An estimate of approval workload (drafts per day, per user)
Simulate is the safety net. It’s the difference between “the playbook looks reasonable” and “the playbook would have produced 240 emails to one customer last Tuesday.” Always simulate before going live.
The simulation runs in a sandbox. It does not call send_email, send_slack, send_sms, or call_external for real. It produces drafts you can read but never delivers them.

​
Step references

Steps can reference each other’s outputs. The reference syntax is {{ stepN.field }} or {{ stepN.collection[*].field }} for arrays. 
steps:
  - tool: query_collection
    collection: deals
    filter: "amount > 10000 AND stage = 'proposal'"
    limit: 50
  - tool: query_collection
    collection: contacts
    filter: "id IN {{ step1.deals[*].contact_id }}"
  - tool: draft_for_approval
    template: proposal_followup
    recipient: "{{ step2.contact.email }}"
    context:
      deal_name: "{{ step1.deal.name }}"
      deal_amount: "{{ step1.deal.amount }}"

​
Guardrails

Guardrails bound what a playbook can do regardless of its steps. They are the policy layer that exists outside the agent’s reasoning.
GuardrailWhat it does
Risk tierOne of draft_and_approve, auto_with_undo, auto. See risk tiers.
Rate limit per userMax drafts a single user can be the owner of in a window
Rate limit per recipientMax drafts that can target a single recipient in a window
Allowed recipientsWhitelist of domains or addresses
Excluded recipientsReference to a do_not_contact collection
Scopeapp_wide or personal (scopes)
Max stepsHard cap on tool calls per playbook run
Max recursionPrevents a playbook from triggering itself unbounded

​
Common playbook shapes

​
Watch and notify

trigger:
  type: data_change
  collection: tickets
  on: [create]
  where: "priority = 'p0'"
steps:
  - tool: notify_user
    recipient: "on_call_user"
    message: "P0 ticket: {{ trigger.record.title }}"

​
Watch and draft

trigger:
  type: data_change
  collection: deals
  on: [update]
  where: "stage = 'lost'"
steps:
  - tool: draft_for_approval
    template: lost_deal_postmortem
    owner: "{{ trigger.record.owner }}"

​
Schedule and digest

trigger:
  type: schedule
  cron: "0 8 * * 1-5"
steps:
  - tool: query_collection
    collection: deals
    filter: "owner = {{ context.user_id }}"
  - tool: draft_for_approval
    template: daily_briefing
    owner: "{{ context.user_id }}"

​
Inbound and route

trigger:
  type: webhook
  source: stripe
  event: invoice.payment_failed
steps:
  - tool: query_collection
    collection: customers
    filter: "stripe_id = {{ trigger.body.customer }}"
  - tool: draft_for_approval
    template: payment_failed
    recipient: "{{ step1.customer.email }}"
    owner: "{{ step1.customer.account_owner }}"

​
Editing playbooks

Edit through chat or the editor: 
Update the stalled-deal playbook to also cc the
sales manager when the deal is over $50,000.

Add a guardrail to the daily-briefing playbook:
max one draft per user per day.

Change the SLA-enforcer playbook trigger from
every hour to every 15 minutes.

​
Best practices

A 30-day simulation catches load problems, recipient explosions, and bad filters before they reach real users.
“Nudge stalled deals” is a clear playbook. “Manage the sales pipeline” is a bundle of five playbooks pretending to be one.
The default for outbound work is draft_for_approval for a reason. Graduate to auto_with_undo only after a clean approval history.
A do_not_contact collection lets you opt specific records out without breaking the whole playbook for everyone else.

​
Learn more

Triggers

Schedule, data change, webhook, user-triggered

Tools

The fixed registry of tool calls

Risk tiers

Draft-and-approve, auto-with-undo, auto

Recipes

Worked examples of common playbooks