Brainforge Knowledge

PLAYBOOK_SCAFFOLD

4 min read

Playbook Scaffold

Use this scaffold when creating a reusable, client-agnostic playbook from repeated delivery, GTM, legal, or operational work.

What a playbook is

A playbook is a repeatable operating procedure for humans and agents:

  • reusable across more than one client, engagement, or teammate
  • explicit about inputs, decision points, and outputs
  • clear about approval gates before high-impact actions
  • grounded in one or more real implementations, while keeping the reusable doc client-agnostic

If the asset is primarily:

  • client-specific → keep it in the client repo or knowledge/clients/...
  • a standard template → put it in knowledge/standards/02-writing/
  • dynamic agent behavior with tool steps and independent trigger phrases → consider a Cursor skill instead

See also:

  • knowledge/KNOWLEDGE_AND_STANDARDS_GUIDE.md
  • knowledge/sales/services/README.md
  • knowledge/standards/PLAYBOOK_DEVELOPMENT_PLAN.md

Placement rules

Choose the path based on the domain that owns the workflow.

SituationPreferred home
Delivery workflow tied to a service line / subserviceknowledge/delivery/service-lines/{line}/{subservice-or-slug}/playbooks/
Domain playbook without service-line ownership (for example Legal)knowledge/{domain}/playbooks/
GTM partner / sales motionexisting domain playbook folder under knowledge/sales/.../playbooks/

When a local playbooks/README.md exists, update it in the same change.

Label and taxonomy rules

  • Use exactly one primary service line when the playbook maps to Brainforge delivery taxonomy.
  • Use exactly one primary subservice when the work is subservice-specific.
  • Use display names in prose and keep current Linear slugs in backticks where useful.
  • If a workflow touches two subservices, pick the primary one by the center of gravity of the work and explain the secondary context in prose. Do not present two primary labels.

Current Data examples:

  • Data Platform → data-infrastructure
  • Data Modeling → analytics-bi

Authoring rules

  • Keep the playbook client-agnostic.
  • Put canonical reusable logic in the playbook; put concrete SQL, dbt models, screenshots, and client implementation details in the relevant repo and link to them.
  • Prefer deterministic steps over vague advice.
  • Call out failure modes, exceptions, and approval gates explicitly.
  • Use short, imperative section prose that agents can follow without guessing.
  • Default new entries in PLAYBOOK_INDEX.md to Draft unless they have already been internally reviewed and are ready to be treated as published.

Required sections

Every playbook should include these sections unless there is a strong reason not to:

  1. # Playbook: ...
  2. Version, Last updated, Audience
  3. Purpose
  4. When to use
  5. Service line / subservice or domain ownership
  6. Approval-before-execution pipeline (if any high-impact action exists)
  7. Scope
  8. Prerequisites
  9. Inputs
  10. Workflow or Agent algorithm
  11. Failure modes, Exceptions, or Gotchas
  12. Example implementation
  13. Related

Paste-ready template

# Playbook: <title>
 
**Version:** 0.1  
**Last updated:** YYYY-MM-DD  
**Audience:** LLM agents and humans <doing what>.
 
---
 
## Purpose
 
<What this playbook helps someone do, and why it exists.>
 
## When to use
 
Use this playbook when:
 
- <trigger phrase or repeated situation>
- <trigger phrase or repeated situation>
 
Do not use this playbook when:
 
- <adjacent case that belongs somewhere else>
 
## Service line / subservice
 
| Field | Value |
|-------|-------|
| Service line | <display name> → `<slug>` |
| Primary subservice | <display name> → `<slug>` |
| Notes | <optional routing notes> |
 
## Approval-before-execution pipeline
 
<Only include when relevant. Show exactly where the agent must stop for approval.>
 
## Scope
 
**In scope**
 
- <item>
- <item>
 
**Out of scope**
 
- <item>
- <item>
 
## Prerequisites
 
| Requirement | Notes |
|-------------|-------|
| <thing> | <why it matters> |
 
## Inputs
 
| Input | Example | Notes |
|-------|---------|-------|
| <input> | <example> | <notes> |
 
## Workflow
 
### Step 1 — <name>
 
- <deterministic step>
 
### Step 2 — <name>
 
- <deterministic step>
 
## Failure modes / gotchas
 
- <common failure>
- <common failure>
 
## Example implementation
 
<Link to concrete repo paths, scripts, SQL, dashboards, or example files.>
 
## Related
 
- <local README>
- <standards doc>
- <related playbook>

Publication checklist

Before shipping, check:

  • Playbook follows this scaffold or intentionally departs from it
  • Path is correct for the owning domain
  • Local playbooks/README.md updated
  • knowledge/standards/02-writing/PLAYBOOK_INDEX.md updated
  • Client-specific implementation details live in the client repo or knowledge/, not in the reusable playbook itself

Graph View