Using Src Playbooks

Overview

Src Playbooks is a workflow automation engine built on top of Span's Src AI assistant. Playbooks let your organization define automated, recurring workflows that are triggered by Slack messages or on a recurring schedule — running a Src agent to answer questions, generate reports, and deliver results without any manual intervention.

How Playbooks Work

A playbook combines three things:

1. A trigger — when the playbook runs (a Slack message pattern or a cron schedule)

2. Instructions — what the Src agent should do when triggered

3. Tool access — which data sources Src can query (code, metrics, surveys)

Once created and enabled, playbooks run fully automatically. Each run is tracked individually with a status and execution history.

Playbook Types

🗨 Conversational Agent

A Conversational playbook monitors one or more Slack channels and responds in-thread when a message matches its trigger.

Best for:

• Auto-answering recurring questions (e.g., "What's the status of the deploy?")

• Providing code or metric context when incidents are posted

• Surfacing relevant engineering information in real time

How matching works:

Span uses a two-stage matching process:

1. Channel filter — only messages from the configured channels are considered

2. Semantic match — an AI model checks whether the message content matches the playbook's stated intent

This means the playbook responds to the meaning of a message, not just exact keyword matches.

Note: Conversational playbooks respond to root channel messages only. Replies in threads are ignored by default.

📅 Scheduled Task

A Scheduled playbook runs on a recurring cron schedule and delivers its output to a Slack channel, DM, or email address.

Best for:

• Weekly engineering digests

• Daily standup summaries

• Automated metric reports for leadership

• Recurring health checks on team data

Creating a Playbook

Go to Settings → Playbooks and click New Playbook.

Fields

Trigger Configuration

Write your trigger in plain English. Span automatically resolves it into a structured configuration as you type, showing you the resulting channel selectors or cron schedule in real time.

Example trigger inputs:

For conversational playbooks, the resolved trigger will include the matched channels (by exact name or prefix) and whether only root messages are checked.

Tool Access

You can control which data sources Src uses during a playbook run. All three are enabled by default.

Restricting tool groups can improve focus or limit data scope for specific use cases. For example, a playbook that only summarizes metrics doesn't need code exploration access.

Instructions

The Instructions field tells Src what to do when the playbook fires. Write it as a free-form task description.

Action Directives (Scheduled Playbooks)

For scheduled playbooks, use action directives at the end of your instructions to tell Src where to deliver the output.

Multiple directives are supported — results will be delivered to all specified destinations.

Example Instructions:

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

Directives are validated in real time as you type. Any invalid directive will be flagged before you can save.

Managing Playbooks

From the Playbooks list you can:

• Enable / Disable a playbook using the toggle — disabled playbooks stop running immediately

• Edit the trigger, instructions, tool groups, or delivery settings at any time

• Delete a playbook (requires confirmation)

• View each playbook's run count and last run timestamp

The list shows the playbook name, creator, type, destination (channel or schedule), number of runs, last run time, and current status (Active or Disabled).

Testing a Playbook

Scheduled playbooks support a Test Run option, accessible after saving the playbook. Use this to trigger a one-off execution and verify the output without waiting for the next scheduled run.

The Test button is only available after the playbook has been saved at least once.

Execution & Reliability

• Every run is tracked independently with a status: Pending, Running, Completed, or Failed

• Span prevents duplicate runs using idempotency — if the scheduler evaluates a window twice, the playbook runs only once

• Scheduled playbooks include a delay tolerance window (minimum 45 minutes): a run that fires slightly after its scheduled time won't trigger again within that window

• Failed runs log an error message you can inspect to understand what went wrong

Permissions

Creating, editing, enabling/disabling, and deleting playbooks requires the Playbooks Manage permission. Contact your Span administrator if you need access.

Example Playbook Configurations

Conversational: Deployment Status Bot

Answers deployment questions posted in your team channel

• Type: Conversational agent

• Trigger: "Questions about deployment or release status"

• Channels: #eng-team

• Instructions: "Check the latest deployments and open PRs, then summarize the current release status"

• Tools: Knowledge graph and metrics, Code exploration

Scheduled: Weekly PR Summary

Posts a weekly digest every Monday morning

• Type: Scheduled task

• Trigger: "Every Monday at 9am"

• Instructions:

  Generate a summary of last week's pull request activity. Include:
  - Total PRs merged
  - Average cycle time
  - Top contributors
  - Any PRs still open from last week
  
  /slack:message #engineering
  

• Tools: Knowledge graph and metrics

Scheduled: Monthly Leadership Report

Emails a monthly engineering metrics brief to the VP of Engineering

• Type: Scheduled task

• Trigger: "First of every month at 9am"

• Instructions:

  Create a monthly engineering performance report including:
  - Deployment frequency trends
  - PR cycle time vs. last month
  - Team health metrics from surveys
  
  /email vp-eng@company.com
  

• Tools: Knowledge graph and metrics, Surveys

FAQ

Can a conversational playbook respond in the same thread it was triggered from? Yes — Src replies directly in the thread of the triggering message.

What happens if a run fails? The run is marked Failed and an error message is logged. No delivery is made. You can view the status and error from the Playbooks list.

Can I use multiple action directives in one playbook? Yes. You can include multiple /slack:message, /slack:dm, and /email directives in a single scheduled playbook and results will be sent to all destinations.

What is the minimum schedule cadence? The scheduler evaluates playbooks hourly, so the minimum practical cadence is once per hour. Biweekly and monthly schedules are also supported.

Can I run a conversational playbook on multiple channels at once? Yes. You can configure a trigger that matches multiple channels by name or by channel name prefix (e.g., all channels starting with support-).

What if Src doesn't find relevant information? Src will respond with whatever context it can find and note any limitations. It won't fabricate results.