writing-best-practices

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.