---
name: writing-voice
description: Voice and tone rules for all written content. Use when writing prose that should sound human and be suitable for reading aloud.
---

# Writing Voice

**Core principle**: Write for the ear, not just the eyes. Prose should be suitable to read out loud.

## The Test

Read it out loud. If it:

- Sounds like a press release → rewrite
- Sounds like a corporate memo → rewrite
- Sounds stilted or unnatural → rewrite
- Sounds like you explaining to a colleague → ship it

## AI Dead Giveaways

Patterns that scream "AI wrote this":

- **Bold formatting everywhere**: Never bold section headers in body content
- **Bullet list everything**: Convert to flowing paragraphs when possible
- **Marketing words**: "game-changing", "revolutionary", "unleash", "empower"
- **Structured sections**: "Key Features:", "Benefits:", "Why This Matters:"
- **Vague superlatives**: "incredibly powerful", "seamlessly integrates"
- **AI adjectives**: "perfectly", "effortlessly", "beautifully", "elegantly"
- **Space-hyphen-space**: "The code works - the tests pass"
- **Overusing fragments**: "Every. Single. Time." (once is emphasis, twice is a pattern)
- **Staccato buildup**: Setup. Fragment. Fragment. Fragment. Punchline. This "dramatic reveal" pattern feels manufactured. Combine into one flowing sentence with em dashes or semicolons instead.
- **Forced specificity**: Random numbers that don't add meaning

## Punctuation

Never use " - " (space-hyphen-space) or " — " (space-em-dash-space). Prefer simpler punctuation:

| Prefer        | When                                                           |
| ------------- | -------------------------------------------------------------- |
| Period (.)    | Default choice. Two sentences are often clearer than one.      |
| Colon (:)     | Introducing explanation: "Here's the thing: it doesn't work"   |
| Semicolon (;) | Related independent clauses: "The code works; the tests pass"  |
| Em dash (—)   | Sparingly, for interruption or emphasis: "It's fast—really fast" |

Em dashes are fine but easy to overuse. When in doubt, use a period.

## Voice Matching

When the user provides example text or tone guidance, match it:

- If they're terse, be terse
- If they give 5 sentences, don't write 5 paragraphs
- If they use direct statements, don't add narrative fluff
- Match their energy, not a template