--- name: prose-style description: > The Adom house writing style, applied to ALL user-facing copy you write: NO em-dashes (use a comma, colon, or period), and cut the tics that make text read as AI-generated (delve, seamless, robust, leverage, "it's not just X, it's Y", "in today's world"). Write plainly, like a person. Read before writing any README, wiki page, release note, chat message, UI string, or docs. Enforce with the prose-lint CLI. --- # Adom House Style We ship a lot of copy that customers and teammates read: wiki pages, README files, release notes, chat announcements, UI strings, component descriptions. Much of it is drafted by an AI, and it too often reads that way. This is the standard for all of it. The goal is simple: **it should read like a person wrote it.** Two things give AI writing away, and both are fixable: 1. **Em-dashes.** Models reach for them constantly. People rarely do. 2. **A house dialect** of favorite words and sentence shapes that signal "generated." Fix both and the copy sounds human. ## Rule 1: No em-dashes Do not use the em-dash (`—`), the en-dash in prose (`–`), or a spaced double-hyphen (` -- `) as a substitute. Replace with whatever the sentence needs: - A **comma** for a light pause: `the PCL runs real boards, not simulations.` - A **colon** to introduce: `one job: catch em-dashes before they ship.` - A **period** for two thoughts: `It failed. Here is why.` - **Parentheses** for a true aside: `the watchdog (every two minutes) pulls master.` | Instead of | Write | |---|---| | `real data — feeding back into our models` | `real data that feeds back into our models` | | `it works — fast` | `it works, and it's fast` | | `three sources — JLCPCB, DigiKey, Mouser` | `three sources: JLCPCB, DigiKey, Mouser` | The en-dash is fine in a genuine number range (`2-5 V`, `pins 3-7`); a hyphen reads just as clearly there. Everywhere else, rewrite. ## Rule 2: Cut the tell-words These words cluster in AI copy. Prefer the plain version, or delete. | Tell | Use instead | |---|---| | delve into | dig into, look at | | leverage / utilize | use | | seamless / seamlessly | smooth, simple, cleanly | | robust | solid, reliable | | in-depth | detailed, thorough | | cutting-edge / state-of-the-art | new, modern | | showcase | show | | foster / facilitate | build, help | | streamline | simplify, speed up | | empower / unlock / unleash | let, enable | | myriad / plethora | many | | meticulous | careful | | boasts | has | | game-changer / revolutionize | (just say what changed) | | realm / landscape / tapestry / testament | (name the actual thing) | Hype adjectives (`powerful`, `seamless`, `revolutionary`, `world-class`) usually add nothing. If a claim is true, a concrete number or fact proves it better than an adjective: not "blazing-fast search" but "search returns in under 20 ms." ## Rule 3: Kill the cadence Certain sentence shapes are pure AI tell. Rewrite them into a plain statement. - **"It's not just X, it's Y."** -> say what it is. `It's a search index over three distributors.` - **"Not only X but also Y."** -> a plain list or two sentences. - **"In today's fast-paced world..."** -> delete the opener, start with the point. - **"When it comes to X..."** -> delete; start with X. - **"That's where X comes in."** -> say what X does. - **"Whether you're a beginner or an expert..."** -> cut it. - **"X plays a pivotal role in..."** -> say what X actually does. - **"Look no further" / "Say goodbye to..."** -> ad-copy cliches; delete. - **Rule-of-three padding** ("fast, reliable, and scalable") -> keep the one that's true and specific. - **Rhetorical fragments** ("The result? ...") -> write the full sentence. ## How to write instead - **Lead with the point.** First sentence says what the thing is or does. No windup. - **Be concrete.** Names, numbers, file paths, real behavior. Specifics read as human; abstractions read as generated. - **Short, active sentences.** Prefer "the watchdog pulls master" over "master is pulled by the watchdog." - **Say "use", "help", "start", "show".** Plain verbs over Latinate ones. - **Cut filler.** "in order to" -> "to". "a variety of" -> "several" or a count. Drop "very", "really", "simply", "actually". - **It's fine to sound like an engineer.** Dry and precise beats polished and vague. Litmus test: read it aloud. If you would not say it to a colleague at their desk, rewrite it. ## Where this does NOT apply - **Code, commands, and identifiers.** A `--flag`, a `2-5 V` range, a filename, a URL. Leave them exactly as they are. - **Direct quotes** from a person or a datasheet. Quote faithfully, em-dashes and all. - **Established product names.** ## Enforce it: prose-lint `prose-lint` is the deterministic checker for everything above. Run it before you ship copy: ``` prose-lint README.md # or a wiki page, release notes, any file cat draft.md | prose-lint # stdin works too prose-lint --fix README.md # apply the safe 1:1 word swaps automatically ``` It reports `line:col`, the rule, and a suggestion, and it is code-aware (it will not flag a flag in a code span or a real number range). Em-dashes are the hard rule and fail the check; tell-words and cadence are advisory, because judgment still matters. `--fix` only handles the unambiguous word swaps. Em-dashes and cadence you rewrite by hand, using this guide. Wire it in wherever copy is generated or published: before `adom-wiki page publish`, in README and component-page generators, and before an announcement goes to chat.