Prose Style (Adom House Style)

@@ -0,0 +1,130 @@+---+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.++<!-- prose-lint-disable (the table and examples below name the banned words on purpose) -->++| 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.++<!-- prose-lint-enable -->++## 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.** <!-- prose-lint-disable -->"in order to" -> "to". "a variety of" -> "several" or a count.+  Drop "very", "really", "simply", "actually".<!-- prose-lint-enable -->+- **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.