Using Src Playbooks

Last updated: October 29, 2026

Playbooks run Src, Span's AI research agent, on a schedule or when a matching message is posted in Slack, and deliver the answer to Slack or email without anyone opening Span.

Why it matters

The reports you build by hand every week can arrive on their own. A Monday attention brief, a monthly AI report for leadership, or an answer to a recurring question in a team channel all run from one saved prompt.

How it works

A Playbook combines:

  1. A trigger: when it runs, written in plain English. Either a schedule ("Every Monday at 8am Pacific") or a message in chosen Slack channels.

  2. Instructions: what Src should do when it fires.

  3. Destinations: where a scheduled Playbook delivers its answer (Slack channel, Slack DM, or email).

  4. Tools: which data Src may use during the run.

  5. An executor: whose access the run uses. A run never uses the access of the person who triggered it.

Once enabled, a Playbook runs on its own. Each run is tracked with a status: Pending, Running, Completed, or Failed. From a run in the history, Open in Src shows the full thread.

Playbook types

  • Scheduled task: runs on a recurring schedule (hourly, daily, weekly, biweekly, or monthly), then delivers the result to its destinations. Good for weekly digests, standup summaries, leadership reports, and recurring health checks.

  • Conversational agent: watches one or more Slack channels and replies in the thread when a message matches the trigger. Good for recurring questions such as "What's the status of the deploy?" or adding metric context when someone posts about an incident.

A conversational Playbook matches in two stages. First, the message must be in one of the configured channels. By default only root messages count, not thread replies, unless your trigger says otherwise. Channels can be matched by exact name or by prefix, such as every channel starting with support-. Then an AI model checks whether the message matches the meaning of the trigger, not just its keywords.

Tool groups

Tool group

What Src can use

Knowledge graph and metrics

Engineering metrics, PR history, team data, deployments, and incidents

Surveys

Team survey responses and developer experience data. Src reads responses only when the executor has Manage Surveys.

Web search

Internet search. Available only when an admin turns on Allow internet search queries under Settings → Src.

Code exploration

Shows as unavailable for your organization unless Span has turned on code indexing for it. When it's on, it covers every repository allowed under Settings → Src, whatever the executor's team permissions.

Every available tool group starts on. Turn off any a Playbook doesn't need. For example, a metrics summary doesn't need Surveys.

Tool groups limit what a run may use. They don't add access: each tool still returns only the teams and people the executor can see. Code and the organization catalog (repositories, projects, services, deployments, and incidents) are the exception, because they're organization-wide.

Setup

  1. Click Playbooks in the left navigation, under Organization.

  2. Start from a template, or create a new Playbook.

  3. Enter a name and choose Visibility: Private (only you can see it, the default) or Shared (everyone with Playbooks access can see it).

  4. Write the trigger in plain English. Span shows the schedule or channel matching it parsed, so you can check it.

  5. Write the instructions.

  6. For a scheduled Playbook, add destinations: Slack channel, Slack DM, or Email.

  7. Under Advanced, choose the type, the executor, and the tool groups.

  8. Save, then use Test Run to check the output without waiting for the schedule.

Choosing the executor

  • Run as me (default): the Playbook uses your permissions. If your permissions change, its access changes too. If your user is deactivated or deleted, the Playbook stops working.

  • Service account: the Playbook runs through a service account you're allowed to use, and sees what that service account can access. A service account gets its access from its own settings in Settings → Service Accounts, not from permission groups. You can also create one from the form; Owners and Admins can manage service accounts by default. Use this for shared or long-lived Playbooks.

Destinations in the instructions

You can also add destinations as action directives at the end of the instructions. Span validates them as you type.

Directive

Delivers to

/slack:message #channel-name

A Slack channel

/slack:dm "Full Name"

A Slack direct message to one person

/email user@company.com

An email address

You can use several. The result goes to every destination.

Generate a weekly engineering summary for the past 7 days. Include:
- Top contributors by PR count
- Average PR cycle time compared to the previous week
- Any PRs open longer than 5 days

/slack:message #eng-leadership
/email cto@company.com

You need the Manage Playbooks permission to create, edit, enable, disable, or delete Playbooks. Conversational Playbooks and Slack delivery also need Slack connected to Span. Without it, the form shows "Slack is not configured".

Things to know

  • Run timing. A Playbook runs within 45 minutes of its scheduled time. If it can't start in that window, Span skips that slot and runs it at the next one. A Playbook never runs twice for the same slot.

  • Supported schedules. Hourly, daily (weekdays), weekly on one day, every few weeks (for example biweekly), and monthly on the 1st. The shortest interval is one hour. If you don't name a time, Span picks a sensible default such as 9 AM.

  • A Playbook shares its executor's view. A Playbook runs as its executor, not as the person whose message triggered it. Anyone who receives the output sees data scoped to the executor. If the executor can see more than the people receiving it, the answer can include more than they could see in Span, and a Slack delivery posts it where everyone in that channel can read it. For example, a "Run as me" Playbook from a director that posts to a broad channel shows that director's data to the whole channel. Use a service account with narrower access when that matters.

  • Scheduled runs send without asking. No one approves each message. The Playbook's destinations and tool groups are what limit it.

  • Check the output. Src answers from the data its tools return and notes gaps, but it can still use the wrong team or time window. Review the first few runs, and name the team and period in the instructions.

  • Templates are a starting point. Span ships 28 scheduled templates, such as "Weekly executive attention brief", "AI usage, week over week", and "Where time went". Each emails the creator by default, and most scope themselves to "the teams reporting to me".

  • Disabled Playbooks stop at once. On the Playbooks list, open the menu next to a Playbook you created and choose Disable. The list shows each Playbook's name, author, destination, created date, and status (Active or Disabled).

Examples

  • Conversational: deployment status. Trigger: "Questions about deployment or release status in #eng-team". Instructions: "Check the latest deployments and open PRs, then summarize the current release status." Tools: Knowledge graph and metrics.

  • Scheduled: weekly PR summary. Trigger: "Every Monday at 9am". Instructions: "Summarize last week's pull request activity: total PRs merged, average cycle time, top contributors, and PRs still open from last week." Destination: /slack:message #engineering. Tools: Knowledge graph and metrics.

  • Scheduled: monthly leadership report. Trigger: "First of every month at 9am". Instructions: "Create a monthly engineering report with deployment frequency trends, PR cycle time versus last month, and team health from surveys." Destination: /email vp-eng@company.com. Tools: Knowledge graph and metrics, Surveys.

FAQ

  • Does a conversational Playbook reply in the same thread? Yes. Src replies in the thread of the message that triggered it.

  • What happens if a run fails? The run is marked Failed with an error message, and nothing is delivered. You can see it in the run history.

  • What if Src doesn't find relevant data? Src answers with what it found and says what's missing. Treat a surprising number, such as zero, as a reason to check the scope and window.

Related articles

Using Src to understand your engineering metrics

Src Slack Setup Guide

Service Accounts

Need help?

Contact your Span account team or reach out to support@span.app.