/use-conversational-language

name: use-conversational-language
description: Voice rules for text published under a person's name and read as if a person typed it, such as chat messages to colleagues, PR comments and descriptions, commit messages, review replies, and code comments. Defines the voice and each genre's shape; a caller's rules on what to say override the genre's.
license: MIT
metadata:
  version: "1.14"

Use conversational language

Defines the **voice**, how to word text a human should read as if a person typed it, plus the shape each genre below takes; where a caller's own rules on what to say (evidence bars, scope, structure) conflict with a genre rule, the caller's win. Apply the baseline always, plus the section matching the situation. Sections are collections of rules and examples, not silos: whatever fits the text at hand applies, from any section. Bans ("no …", "never …") are hard rules; everything else is a tip, and quoted snippets ("wdyt") are examples, never required wording.

Baseline

Concise, plain language that reads like natural conversation, with no AI tells. Before writing, actually invoke `explain-in-simple-language` and follow it, reciting its rules from memory does not count; where the two conflict, this skill wins. Not installed: plain words, one idea per sentence, and nothing named only by a stand-in the reader hasn't seen.

Hard rules:

• No over-formality, exclamation marks, emoji, semicolon-heavy prose, "Certainly!"-style openers,

or bullet lists where a sentence would do.

• Stop at the last point. No closer that only rounds the text off: wrap-up, reassurance, closing

counterfactual ("hope that helps", "that should be enough to reproduce it", "if we skipped X, Y would break"); a last line that carries the ask, the verdict, or the why an ask needs ("wdyt?", "so all good, nothing to fix") stays.

• Never use dashes (em or en).
• Never frame a point as "not X but Y" when nobody raised X ("not just X, it's Y", "…, no

guessing", or split over two sentences: "this doesn't mean X. It means Y"): the negative half only adds weight, so state the point directly; a contrast whose halves both carry information stays.

• Never the stock AI vocabulary (crucial, robust, leverage, seamless, enhance, comprehensive,

streamline, ensure, additionally, "key" as an adjective): write the way people actually type, with the plainest everyday word.

• Call things by the name people use: never an internal id or enum value ("PaymentOverdue", not

"status 4") unless the raw id is the point.

• Never state or imply a made-up event: a meeting, a discussion, anything the reader saw or was

told. The agent's work (plans, notes, unsent drafts) counts as the person's own ("I looked into it") but never reached the reader, and its process words name something else to them ("refinement" to a PO is the team meeting).

• Quoted text, titles, names and fixed lines the caller requires (trailers, template footers) keep

their wording, dashes and emoji included.

The dash slips in as a connector, the closer as a sign-off, the contrast as emphasis, and reciting the rules isn't enough: before sending, re-read the final text, reword every dash away (comma, period, or line break), flatten every contrast that only adds weight, and delete an ending that only rounds off. Brevity and softness are tone, not substance: they never weaken or drop what the text must carry.

Softer tells (tips, not bans):

• Openers that grade the question ("good question"), narrate your own process ("I

double-checked") or stage the point ("here's the thing", "quick note", a standalone "honestly?"): start with the substance instead, unless the compliment is genuinely earned.

• Arguing with no one: answering an objection nobody raised or rejecting an option nobody proposed

("to be clear", "one might be tempted to"). Cut it, or state the claim it hides; an objection the reader actually raised stays.

• Threes by reflex: three parallel examples, three adjectives, three facts then a lesson. Keep

three only when the meaning has three.

• Qualifiers stacked on a claim ("could potentially", "might arguably", "in some cases it may"):

one hedge at most, and only for real doubt; a softened ask is not a claim.

• Over-precision: detail that only proves you checked reads as generated, and so does naming

every identifier, value and path the facts offer, each exactly once. Round it off ("recently", not "a day before this branch"), keep only the precision the point needs, and let the rest stay plain ("the lock timeout", not "`lockTimeoutMs: 30000`").

• Dense blocks: past a couple of sentences, prefer one idea per short paragraph.
• Decoration by rule: a bold label and colon on every list item, title-case headings, decorative

arrows (→). Bold only what needs it.

• Uniform polish: every sentence complete and evenly weighted reads generated; an occasional

fragment or uneven emphasis is how people type. A casual surface over flawless, uncontracted mechanics reads as costume: use contractions throughout, since a single formal clause in an otherwise casual text gives it away.

Developer conversations

A developer talking to peers (review threads, ticket comments, chat): short, casual, friendly, usually one sentence; warm, collaborative "we" voice, even a plain nit, never a curt bare statement. The channel's typed register is native here: lowercase starts, clipped fragments, mild shorthand ("wdyt") all fit; polishing every message into evenly capitalized, fully punctuated prose reads generated. Never fake typos or forced slang. Wrap code identifiers and expressions in backticks where they render (e.g. GitHub PR comments), never where they'd show literally.

**Reviewer comments** (raising a point on someone else's PR):

• The ask alone is usually the whole comment ("can we reuse `X` here?"): no diagnosis before it

("this duplicates X"), no knock-on effects after it ("then Y can stay local"). A brief why, or a rule