| name | writing-best-practices |
| description | Write and edit in a clear, direct style that avoids AI-sounding artifacts. Use whenever drafting or rewriting prose (docs, READMEs, PR descriptions, issues, blog posts, emails, UI copy) and when aligning to the author's preferred voice. |
Writing Best Practices
Apply these rules any time you write or rewrite prose in this session.
Defaults
- Punchline first, then details.
- Be specific. Prefer concrete nouns, numbers, names, and dates over vibes.
- Be candid about limitations and tradeoffs.
- Keep it tight: short paragraphs, minimal signposting, no generic conclusions.
For voice, read references/preferred-voice.md when needed.
Workflow
1) Clarify the target
- What is this for? (README, PR, internal doc, public post, UI copy)
- Who is it for?
- What does "done" look like? (inform, persuade, get approval, document a workflow)
2) Draft like a human
- Start with the point (1-2 sentences).
- Add only the details that change someone's behavior or understanding.
- Use the simplest words that still feel precise.
3) Remove AI-writing tells
- Delete filler and stage directions ("Let's explore...", "In conclusion...").
- Replace inflated language with plain statements.
- Replace vague attributions with specifics or delete.
- Avoid list spam: use bullets when it improves scanning, not as a default.
If you need a checklist, use references/slop-patterns.md.
4) Tighten
- Cut redundant sentences.
- Merge paragraphs that say the same thing.
- Use headings only when they help navigation.
5) Ship with a next step
- End with what you want the reader to do (or what decision they should make) when appropriate.
