# Playbook documentation (docs/architecture/playbooks/{subject}.md)

Truth document. Use for **one interface or workflow shape every product builds**: the shell, a settings area, analytics pages, a record's lifecycle, the interaction patterns, automated agents. One file per shape, named for it. A playbook speaks for no code: no source header names it, and it carries no `owns:`. The product's own feature documents hold its instance of the shape, and each names the playbook in its Scope.

**A playbook states the shape, never one product's instance of it.** It says what the parts are, how they are arranged, how each behaves and what the shape promises, so a new instance is new content poured into a known shape rather than a new layout. A product's own values (its labels, routes, limits, timings, the wording of its copy) belong to its feature document. A playbook explains no mechanism, for the reasons a doctrine document explains none (`templates/doctrine.md`).

**Doctrine or playbook.** A doctrine document settles the decisions of one concern every product handles, such as how authorization works. A playbook settles what a person sees and does in one recurring shape, such as how a settings page is laid out. A playbook cites the doctrine its shape rests on, and never restates it.

**A playbook is written in general form, never linked to the project that holds it.** It reads correctly when copied verbatim into any other product's repository, under the same rule a doctrine document keeps (`templates/doctrine.md`). Where the shape needs a word for the product's own record, the Purpose introduces a generic one once ("the subject: the record a report is read per, such as a job in a hiring product") and the body uses it throughout. Its links reach only sibling playbooks, doctrine documents and published standards.

**Earn the document, and ask before writing it.** List the rules only this playbook would own, each checked against the playbooks and doctrine that exist. Fewer than about six owned rules means the shape is a section of a neighbour, not a document. A new playbook is created only with the user's approval (SKILL.md § Doctrine and playbooks).

**Required:**

- the frontmatter
- **Purpose:** what the shape is for, what it is not for, and the generic words it introduces
- **Related documents**

**Optional, each only with something real to say:**

- **Anatomy:** an ASCII diagram of the arrangement with each region labelled, then one bullet per region
- **One section per part** that carries rules of its own, named for the part ("Roster", "Readiness", "Side peek")
- **States:** one table — State · Entered when · The person sees · Can do
- **Affordances:** what a person can do, one bullet per verb
- **Principles:** numbered, each a noun-phrase label and its rule
- **Promises:** what the shape guarantees, grouped under `###` headings where there are several kinds
- **Transitions:** what moves the shape between its states, and who moves it

Sections run Purpose first and Related documents last; the rest follow the order above. Each is named for its concept, never for its layer. Expect one hundred to two hundred lines.

```yaml
---
type: playbook                                   # required tooling key
description: "{at most 300 characters: the shape this playbook settles, and that a product's own instance is its feature doc}" # required
status: active                                   # required — active | draft
objects: [rail, command palette, account menu]   # required — the parts this playbook shapes, by their graph names
---
```

```
# {Shape} playbook

## Purpose

{What the shape is for and what it is not for, in two or three sentences. The generic words it introduces, each in one bullet.}

## Anatomy

{An ASCII diagram, then one bullet per labelled region.}

## {Part}

- **{Rule label}:** {the rule, in general form}

## Principles

1. **{Label}:** {the rule}. {Its reason, as a separate sentence.}

## Related documents

- [{Sibling playbook}]({file}.md): {what it settles beside this one}
- [{Doctrine}](../doctrine/{concern}.md): {the decision this shape rests on}
```