Writing Toasty Prose

Load this skill whenever writing or editing prose for this project: documentation in docs/, READMEs, design docs, PR descriptions, issue bodies, commit message bodies, or any other human-readable markdown.

Writing Style

• Be fact-focused: State what things are and what they do
• Avoid buzzwords: No "leverage", "synergy", "paradigm", etc.
• Avoid fluff: Every sentence should convey information
• Avoid business jargon: No "stakeholders", "deliverables", "action items"
• Avoid weasel words: No "very", "really", "quite", "somewhat"
• Avoid dramatic terms: No "critical", "crucial", "vital", "essential" unless something will actually break
• Avoid figurative metaphors: Pick the literal word for the thing, not the analogy. "Features light up on PostgreSQL" → "Toasty enables features on PostgreSQL". "Query shape" → "query pattern" or "query form". Other recurring offenders: "under the hood" (just describe what's there), "out of the box" (just say "by default"), "first-class" (say what's actually supported), "magic" (say what the code does). If you can't replace the metaphor with a literal noun or verb without losing meaning, you probably don't know what you mean yet.
• Be direct: Say what you mean without hedging
• Use concrete examples: Show, don't tell
• Use active voice: "The engine executes queries" not "Queries are executed by the engine"
• Use present tense: Describe how the system works now, not how it was designed or how it will work
• Document current behavior only: Omit historical decisions, deprecated approaches, and planned future work

Examples

Bad: "This component is critical for ensuring optimal query performance."

Good: "This component optimizes queries by combining multiple database round-trips into one."

Bad: "The simplification phase leverages various transformations to enhance query efficiency."

Good: "The simplification phase rewrites association traversals into explicit subqueries."

Bad: "Native arrays light up on PostgreSQL for Vec<scalar> fields."

Good: "On PostgreSQL, Vec<scalar> fields use native array columns (text[], int8[], …)."

Bad: "## Query shapes that work"

Good: "## Supported queries"

Document Structure

• Start with what the thing is
• Explain why it exists (what problem it solves)
• Explain what it does
• Show how to use it (if applicable)
• Provide examples