Writing in Your Voice
How to write a voice document agents can actually follow, and how to correct an agent that keeps getting it wrong.
Most voice documents describe a personality ("confident, human, never salesy") instead of giving rules a writer could follow. An agent reads that and produces the copy it would have produced anyway.
Write Rules, Not Adjectives
| Instead of | Write |
|---|---|
| "Be concise" | "Opening paragraph: max 40 words. No throat-clearing sentence before the point." |
| "Be human" | "Use contractions. Second person. Never 'organizations' when you mean 'teams'." |
| "Avoid jargon" | "Banned: solution, leverage, seamless, best-in-class, unlock, in today's landscape." |
| "Be credible" | "Every claim gets a named customer or a number. If neither exists, cut the claim." |
| "Confident, not arrogant" | "State the limitation before the benefit when there is one. Never compare on price." |
A Voice Document That Works
# How we write
## Sentences
Short. One idea each. Cut the first sentence of most paragraphs. It is usually
setup for the second.
## Words we do not use
solution · leverage · seamless · robust · best-in-class · unlock · empower ·
"in today's fast-moving landscape" · "we're excited to announce"
## Words we do use
Buyer, not prospect. Meeting, not demo, unless it really is a demo.
Agent action, when we mean the billing unit. Never "credit".
## Claims
Name the customer or drop the claim. "Teams see better conversion" is not a
sentence we ship; "Nextiva saw 37% more users convert" is.
## Structure
Lead with the specific thing. Context second, if at all. If the piece could open
on paragraph three, open on paragraph three.Correcting an Agent
When a draft is wrong, fix the Vault and re-run it. Rewrite the draft instead and you make the same edit every week.
Name what was wrong in one sentence
Not "this feels off". Try "it opened with a generic industry statement and used 'solution' twice".
Find the document that should have prevented it
Usually brand/voice.md. Sometimes product/positioning.md, when the agent
is right about the voice and wrong about the claim.
Add the rule, not the fix
Add "never open on an industry statement" to the document. Do not paste the corrected paragraph in.
Re-run the same prompt
If the output still breaks the rule, the rule was ambiguous. Make it narrower and more literal.
SAM reads brand/voice.md before drafting and tells you
when it found no rules to follow, so you learn what is missing without leaving
Slack. Adding the rule itself is an edit in the app.
Style Learnings
Keep corrections in one place:
# Learned corrections
- 2026-08-14: Stopped saying "AI-powered". We say what the agent does instead.
- 2026-08-28: Comparison pages must state where the competitor is genuinely
better, in the first half. Reads as credible; buyers check.
- 2026-09-02: Never "unlimited" without the footnote about fair use.Folders and Structure
The layout we recommend (brand, product, customers, competitors, sales, strategy), and why grouping documents makes them easier to point an agent at.
Vault + Agents
What is documented about agents reading the Vault, how to point one at a document, and how to tell whether a draft actually used it.