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.