# Writing in Your Voice



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 [#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 [#a-voice-document-that-works]

```markdown
# 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 [#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.

<Steps>
  <Step title="Name what was wrong in one sentence">
    Not "this feels off". Try "it opened with a generic industry statement and
    used 'solution' twice".
  </Step>

  <Step title="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.
  </Step>

  <Step title="Add the rule, not the fix">
    Add "never open on an industry statement" to the document. Do not paste the
    corrected paragraph in.
  </Step>

  <Step title="Re-run the same prompt">
    If the output still breaks the rule, the rule was ambiguous. Make it
    narrower and more literal.
  </Step>
</Steps>

<Tip>
  [SAM](/platform/vault/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.
</Tip>

## Style Learnings [#style-learnings]

Keep corrections in one place:

```markdown
# 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.
```