| name | writing-style |
| description | Reviews and writes text for clarity, tone, and consistency. Use when writing UI copy, documentation, handbook content, or error messages. |
Writing Style
STARTER_CHARACTER = ✍️
Review and write text that's clear, helpful, and human.
Adapting to Project Context
Check for existing voice guidelines (docs/handbook, CLAUDE.md, style guides). When found, follow them. When none exist, use the defaults below.
Default Voice
Tone: Friendly and direct. Like a helpful colleague, not a corporate manual.
Qualities:
- Clear: Say what you mean. No jargon unless the audience expects it.
- Concise: Every word earns its place. Cut filler.
- Human: Write how people talk. Contractions are fine.
- Helpful: Guide toward action, not just describe state.
Punctuation
Avoid dashes and em-dashes. Use colons, periods, or restructure the sentence instead.
Anti-pattern: "Couldn't save — you're offline"
Content Categories
Buttons & Actions
Use action verbs. State what happens, not what the element is.
Anti-patterns:
- "Submit": vague
- "OK": doesn't describe action
- "Click here": describes mechanics, not outcome
- "Process": passive, corporate
Destructive actions: be explicit about what will be destroyed.
Error Messages
Help users fix the problem. Structure: what happened, then what to do.
Anti-patterns:
- "Error 500": meaningless to users
- "Invalid input": which input? why?
- "Something went wrong": no guidance
- Blaming language ("You failed to...")
Empty States
Empty isn't an error. It's an opportunity to guide action.
Anti-patterns:
- "No results": dead end
- "Nothing here": states obvious, doesn't help
- Blank screen with no guidance
Labels & Headings
Be specific. Generic labels force users to guess.
Anti-patterns:
- "Settings" (for what?)
- "Details" (which details?)
- "Manage" (manage what?)
Tooltips & Help Text
Explain the non-obvious. Don't repeat what's already visible.
Anti-patterns:
- Tooltip on "Save" button: "Click to save" (useless)
- Help text restating the label
- Walls of text
Tooltips should explain why, when, or edge cases.
Confirmation Dialogs
State the consequence clearly. Make the action button match the question.
Anti-patterns:
- "Are you sure?" + "Yes/No": yes to what?
- Vague consequences ("This action cannot be undone")
- Action buttons that don't match the question asked
Documentation & Handbook
Same principles apply: clear, concise, human.
Additional considerations:
- Lead with what the reader needs to do, not background
- Use headings that answer questions ("How do I..." not "About the...")
- Keep paragraphs short. Scannable over walls of text.
- Code examples over lengthy explanations when applicable
Terminology Consistency
Pick one term and stick with it. Document choices if the project doesn't have a glossary.
Anti-patterns:
- "Map" in one place, "guide" in another for the same concept
- "Remove" vs "delete" used interchangeably
- "User" vs "member" vs "account"
A mini-glossary keeps terms consistent:
place (not: location, spot, point)
adventure map (not: guide, collection)
curator (not: editor, creator, admin)
Accessibility
- Avoid directional references ("click the button on the left")
- Don't rely on color alone ("fields marked in red")
- Keep reading level accessible (aim for grade 8 / age 14)
- Labels should make sense out of context (for screen readers)
Localization Readiness
Avoid patterns that break in translation:
- Don't concatenate strings ("You have " + n + " items"). Use templates with placeholders.
- Avoid idioms ("piece of cake", "ballpark figure")
- Leave room for text expansion (German/French often 30% longer)
- Don't embed formatting in copy ("Click here"). Emphasis may not translate.
Review Checklist
When reviewing copy in a feature or document:
