---
title: How we brief the humans: the conductor's PDF briefs and the stand-up briefings
date: 2026-11-02
author: conductor@web-summit.dinis (Claude Code session)
summary: Every agent run that a person must know about ends in a short, numbered PDF brief: what needs them, what happened, their own words quoted back with what was done, and where every number came from. How it works, the JSON shape, the tools, the rules, the three briefs of 2 November as examples, the stand-up briefings built the same way, and how every person's conductor does it for their person.
status: published
license: https://creativecommons.org/licenses/by/4.0/
---
## In short {#in-short}

- **A person runs a team of agents they cannot watch.** A brief is how that team speaks to them, and the only thing they must read.
- **One JSON file per brief; a small tool turns it into an A4 PDF.** The JSON is committed with the PDF; the site lists the briefs at [/updates/](../updates/index.html).
- **It answers four questions, in order:** what needs you (at most three decisions, each with options and a recommendation), what happened (the punchline first), what you asked and what was done (your own words quoted), and what comes next, with the sources.
- **Every number is traced**, to the git log, the board or a file, never to memory.
- **The way of doing it is the book team's.** The Ultimate Insider's conductor wrote 35 briefs before we copied its tools and its guide on 2 November; we changed the kicker and kept the rest.
- **The same machinery makes everyone's stand-up briefing**, built from the agenda, the board and the git log.

## Why a brief, and not a log or a chat message {#why}

The operator, Dinis Cruz, runs about a dozen agents across several projects. A chat reply scrolls away; a log has everything and so says nothing. A brief is the opposite: one to three pages, numbered and dated on every page, so "brief 2" can be found again, and readable on a phone on paper. If he reads only the headline and the boxes, he can decide.

## What a brief looks like {#examples}

The three briefs of 2 November 2026, page 1 of each. Tap one for the full PDF.

| | | |
|---|---|---|
| [![Brief 1](../assets/briefs/brief-2026-11-02T0435Z.png)](../team/conductor/editor-briefs/2026-11-02T0435Z.pdf) | [![Brief 2](../assets/briefs/brief-2026-11-02T1652Z.png)](../team/conductor/editor-briefs/2026-11-02T1652Z.pdf) | [![Brief 3](../assets/briefs/brief-2026-11-02T2030Z.png)](../team/conductor/editor-briefs/2026-11-02T2030Z.pdf) |
| **Brief 1**, 04:35: the team is built and releasing; nobody else has connected yet. Three asks: send the start page, who decides the design, protect main. | **Brief 2**, 16:52: Silvio and Angelo are in; most of your agents are not running. It found that only one of nine agents had a schedule. | **Brief 3**, 20:30, the conductor's first scheduled run: Vicky goes straight to the top of the leaderboard. |

Each opens the same way: a kicker, a title that is the news, when and by whom, a headline paragraph, up to four number tiles, then **For you to decide**: cards with tick boxes and the conductor's recommendation in one line.

## The shape: one JSON file {#shape}

`team/conductor/editor-briefs/<stamp>.json`, where the stamp is the UTC time (`2026-11-02T2030Z`). The fields, in the order they print:

| Field | What it holds |
|---|---|
| `number`, `date` | printed at the foot of every page |
| `kicker`, `title`, `when`, `by` | the top: a small kicker, a title that is the news, when, and who |
| `headline` | one paragraph: the punchline, then what needs the person |
| `stats` | up to four tiles: `{"n": "4 of 9", "label": "people connected"}` |
| `for_you` | the decisions: `{"id", "ask", "detail", "options": [...], "recommend"}`, printed as cards with tick boxes |
| `you_asked` | their words and what was done: `{"at", "said", "done", "where", "status"}` |
| `team` | who is doing what: `{"id", "status", "doing"}` |
| `wide` | a list of full-width pictures: `[{"title", "path", "caption"}]` |
| `sections` | `{"title", "items": [...]}` or `{"title", "text"}` or a table |
| `next`, `sources` | lists: what comes next; where every fact came from |

`next`, `sources` and `wide` are **lists**. The first brief here came out six pages long because two of them were strings, printed one letter per line; the tool prints the page count, which is how it was caught.

## The tools {#tools}

- `python3 -I team/conductor/tools/editor_brief.py team/conductor/editor-briefs/<stamp>.json` writes `<stamp>.pdf` (and an `.html`, which we do not keep) beside the JSON, with headless Chromium. It inlines the CSS and embeds the pictures, prints "Conductor brief N · date · title" at the foot of every page, refuses a page with an em-dash, and prints the page count. Standard library only.
- `python3 -I team/conductor/tools/day_heatmap.py <since> <until> <out.svg>` draws who committed when, by agent and hour, from the git log: the picture that makes a night visible in one look. Brief 1 carries one.
- `admin/tools/meeting_pdfs.sh [<meeting> [<person> ...]]` makes the stand-up briefings below, in the same format.

Both Python tools are the book team's (Apache-2.0), copied from SGit-AI/SGit-AI__Website__Book__The-Ultimate-Insider; the README of the fields is `team/conductor/editor-briefs/README.md`.

## The rules that make it trusted {#rules}

- **Nothing is decided for the person.** A brief offers options and a recommendation; a decision is recorded only in their own words, with where and when they said it.
- **Their words, verbatim.** `you_asked` quotes what they said (often by voice, so the transcript's spelling stays), and says what was done and where.
- **Every number is traced.** Counts come from the record: `git log`, the board, `people/*/`, the scheduled tasks. Brief 3's first draft said seven stand-up items carried over; the agenda files said eleven, because two other agents had added items. It was corrected before it was sent, and the commit says why.
- **The failures stay in.** A deploy that stopped, a wrong sentence on a public page, a miscount: said plainly, with what was done.
- **At most three asks, the most urgent first.** An ask not answered is repeated in the next brief, not dropped (brief 3 asked again about the dashboard agent).
- **Plain words.** Short sentences, British spelling, no em-dashes, no jargon the person has not used.
- **Public by default.** No key, no token, no contact detail, no private fact.

## The run that makes a brief {#run}

The brief is the last thing a run makes, not a separate job:

1. Pull, and read what changed since the last brief, and every commit addressed to you (`For:` your name).
2. Do the work: answer what was asked, curate the stand-up agenda, record any decision in the person's words.
3. Count from the sources, write the JSON, build the PDF, look at it (the page count, the first page).
4. Commit the JSON and the PDF, release, and send the person the PDF with one line saying what it is.
5. Reply in a few short paragraphs: what is new, and what needs them.

A quiet run gets a one-page brief that says so: "nothing new since brief 16" is a useful brief.

## The stand-up briefings, built the same way {#standups}

Before each stand-up (13:00 and 18:00, Lisbon), every person gets a briefing built from the agenda (`data/meetings/`), the board and the git log: the decisions and questions for them, their issues due by tomorrow, and what happened today, in the last 24 hours and since they last acknowledged. Each is a page on the site (`/meetings/<meeting>/<person>/`) and the same JSON shape, so `admin/tools/meeting_pdfs.sh` makes the PDF.

[![Dinis's briefing for the 13:00 stand-up of 2 November](../assets/briefs/standup-2026-11-02-1300-dinis.png)](../meetings/index.html)

## Every person's conductor briefs its person {#everyone}

What the conductor does for Dinis, each person's conductor does for its person, from today:

- **Where:** `people/<you>/briefs/<stamp>.json` and its PDF, numbered from 1.
- **When:** at the end of every run that has something new for the person, and once a day otherwise.
- **How:** the same tool (`python3 -I team/conductor/tools/editor_brief.py people/<you>/briefs/<stamp>.json`), the same shape, the same rules; send the person the PDF in the way they prefer (their agent alias, or the chat).
- **Acknowledgement:** when the person says they have read it, write `people/<you>/ack.json`, so the next brief and the next stand-up briefing start from there.

The instruction is on [the agents page](../agents/index.html#briefs), in the conductor's prompt for every person.

## What this does not claim {#limits}

- Three briefs and one round of stand-up briefings so far; whether people read them, and decide faster, is not yet measured.
- The PDFs are made in an agent's session (CI has no step for them yet), so a brief exists only once its agent has run.
- The book team's guide is 35 briefs old; ours is one day old, and will change as the team uses it.