Writing briefings, guides and briefs

How we write documents for the team to read. It's a first version (14 Oct 2026), drawn from what has worked so far. Improve it when something works better.

Which kind of document

Kind	What it is for	Where it lives	Example
Briefing	Bring someone up to speed on one topic in about five minutes: what, why, where it stands, what we need from them. A snapshot, dated.	`briefings/YYYY-MM-DD-<slug>.md`	CRM vision, portfolio
Guide	Show someone how to do something, and keep being useful. Kept up to date.	Next to the work it describes, e.g. a repo's `guides/` or `docs/`; list SOPs in procedures	Claude Code across repos, crm guides
Brief	Specify a piece of work before doing it: purpose, shape, decisions, open questions. For the people (or AI) doing the work.	`docs/plans/YYYY-MM-DD-<slug>-brief.md`	AI guide brief

A briefing tells you about something. A guide tells you how to do it. A brief says what we're going to make.

Rules for all of them

TL;DR first. Three to five lines that work on their own. A reader who stops there should still have the point.
The ask near the top. Say what you need from the reader, or say "nothing needed". Don't make them work it out.
Short. A briefing is about five minutes, so 500 to 800 words. Cut anything the reader doesn't need to act or understand. Put detail behind links.
Plain words. Write for a team member who isn't a specialist. Explain or drop jargon and internal names (provider terms, task IDs in prose, acronyms like SCQH).
Link, don't copy. Point to the source document, project record or Beads task rather than repeating it. Keep a "More detail" list at the end. Never copy the task queue.
Quote sparingly and exactly. A short quote from the source can carry a point well. It must be verbatim.
Date the status. Say "as of" for anything that will change, and check it against the live source (Beads, scorecards) before sharing.
Facts come from sources. Don't fill gaps with guesses; mark them as open questions.

Sounding like a person

AI drafts have recognisable tells. Remove them:

Bold everywhere, bold labels at the start of every bullet, emoji status icons.
Em and en dashes used as connectors; use a comma, colon or brackets.
Lists of three for rhythm, "not X but Y" contrasts, inflated words ("robust", "seamless", "key").
A "Detail:" or summary line repeating each heading.
Headings for every small idea. Prose is fine.

Check a draft against soundlikeme's tells and self-check and the Humanizer pattern summary. For Rufus's voice, use the soundlikeme Rufus profile.

How to make one (with AI)

Gather sources and read them. Note the current status from the live tracker.
Skeleton first: headings and one line each. Agree it before drafting.
Draft to the rules above.
Critique with a separate agent: simplicity, clarity, TL;DR and ask, AI tells, length, facts and quotes checked against sources. Ask for a table (issue, quoted context, recommendation) plus a proposed revision.
Apply, then delete the critique. The critique is a working file; don't commit it.
Commit the document and link it from where readers will look (the project record, README or a team update).

When the source is dictation, save it first as a lightly tidied raw note in docs/, then work from that. Once a draft is good, commit it and move it into place; improve it there with further commits rather than holding it back in a draft folder.

Guides that explain concepts

Learned writing Post-its and filing cabinets (15 Oct 2026). For a guide whose job is to build a mental model:

Map the concepts before the skeleton. List each concept, what it depends on, and the order the source introduced them. Try two or three orders through that map, then choose one linear path and say why.
One new idea per step, each with its own picture. Build up from the smallest, most concrete thing (a sheet of paper) to the larger ones. Grow one scene rather than drawing a new world each time.
Metaphor first, tools last. Work the analogy all the way through before mapping it to real systems. Keep anything specific to us in its own final part, so the rest works for any reader.
No front-loaded summary. Open with one line and a map, not a TL;DR that explains everything at once. Mark side points as extras.
Make the map a picture of the argument, not a table of contents. Number the steps, give each a gist of a few words and a small icon, show the flow with arrows, mark the key idea, and show branches and checkpoints (snapshot, recap). Keep it tall and narrow so it doesn't wrap.
Pick a running example that is obviously one project. A summer retreat is clearly one piece of work with an end; "the autumn series" of a podcast left readers unsure what the project was. Keep areas, projects and folders consistent from step to step.
In pictures of documents, write one point per line (what, why, who leads, done by), not a wrapped sentence.

Briefing skeleton

---
title: "Briefing: <topic>"
author: <name>
created: YYYY-MM-DD
status: draft
---

# Briefing: <topic>

## TL;DR
<3–5 lines: what this is, where it stands, what's next.>

## What I need from you
- <ask, or "Nothing needed; for information.">

## <The problem / why>
## <The plan or vision>
## Where it stands (as of <date>)
## What's next
## Open questions
## More detail
- <links to project record, source docs, trackers>