mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
122a82f715
Site copy was being called out as AI slop (specifically the word
"load-bearing"). Five-pass cleanup with a build validator to keep it
from creeping back.
Pass 1 — mechanical purge:
- Remove "load-bearing" from impeccable.md, brand.md, live.md,
iterate-live.md
- Remove "highest-leverage" from critique.md, typeset.md, designing
- Remove em dashes from all 9 slop-page rule cards
- Replace "leverage" verb in personas.md
Pass 2 — rewrite the worst offenders:
- Changelog v2.0 "Data-driven skill rewrite" entry: drop "data-driven",
"frontier models", "collapses into monoculture", "biggest unlock",
"reflex defaults"; name the actual mechanism
- README opener: drop "deeper expertise and more control"; replace with
three concrete differentiators (7 reference files, 23 commands, 27
detection rules)
- Neo Mirai case study opener: action-first, name the image model used
Pass 3 — editorials:
- Fix negation pivot in distill.md ("simplicity is not about ... It is
about ...")
Pass 4 — homepage why-panels:
- Foundation lead: name the 7 reference files specifically
- Language lead: show the discipline mapping with real command names
- Production-codebases panel: drop "Impeccable isn't a sketchpad"
negation pivot
- Ships-code panel: replace "is native to that world" with "runs there"
Pass 5 — STYLE.md and validator:
- New STYLE.md at root: editorial brief with 12 principles and the
enforced denylist (each rule with a rationale and a suggested
replacement)
- scripts/build.js: validateNoEmDashes becomes validateProse. Adds 21
phrase rules with rationales, catches the \`--\` em-dash substitute,
expands target list to site/pages, site/content, README.md,
README.npm.md
- CLAUDE.md: replace the em-dash section with a STYLE.md pointer and
document the two-content-tree footgun (content/site/ vs site/content/
must be edited in lockstep until they're unified)
Co-authored-by: Claude <noreply@anthropic.com>
104 lines
6.4 KiB
Markdown
104 lines
6.4 KiB
Markdown
# STYLE.md
|
|
|
|
Editorial brief for impeccable.design. Read this before writing or editing user-facing copy: the homepage, sub-pages, command editorials, tutorials, and READMEs.
|
|
|
|
The bar: **for every paragraph, point to the sentence that makes it specifically yours.** If you can't, the paragraph is AI by default, even if a human typed it.
|
|
|
|
## Principles
|
|
|
|
1. **Open with the reader's wrong belief, your strongest claim, or the example.** No "in this guide", no "let's dive in".
|
|
2. **Take a position someone could disagree with.** If the paragraph could be inverted without changing meaning, it has no position. Sign your stance.
|
|
3. **Name names. Use numbers.** Real competitors, real customer names, real version numbers, real file paths, real benchmarks. Cut "lightweight"; write "54 KB".
|
|
4. **Verbs lead. Nouns follow.** Imperative is fine. Active voice. Cut nominalizations ("the implementation of" → "implementing").
|
|
5. **Vary sentence length on purpose.** Long, long, short. Smooth uniform rhythm is the deepest AI tell.
|
|
6. **Prose carries the load; structure supports it.** Bullets are for parallel options. Paragraphs are for argument. Don't bullet what would be tighter as a sentence.
|
|
7. **Plain words. Technical terms only when something specifically rests on them.** Mixing levels lets the technical terms hit harder.
|
|
8. **Allow ungrammatical fragments for rhythm.** Five words. Confidence signal.
|
|
9. **Respect the reader's competence.** No "developers should consider"; just "you might not need an effect".
|
|
10. **Read it aloud. Fix anything you stumble over.**
|
|
11. **Concrete over comprehensive.** Coverage is an AI obsession. Trade coverage for momentum. Leave things out.
|
|
12. **Close by handing off the next move.** Don't summarize. End on the strongest sentence, give a directive ("Now do this"), or just stop.
|
|
|
|
## Denylist
|
|
|
|
The build's `validateProse` step (in `scripts/build.js`) fails the build on these. The list is the editorial brief, enforced. Add a rule here when you ban a new pattern; remove a rule when the term has earned a real meaning here. **Do not silently allowlist** by working around the regex.
|
|
|
|
### Stolen-engineer diction
|
|
Engineering words that became AI flavor once they leaked into training data around late 2024.
|
|
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `load-bearing` | Almost always vague. The literal sense is rare. | Name the specific thing it does. "The decision that shapes the rest", "carries the brand", "matters specifically". |
|
|
| `highest-leverage` | Vague claim of impact. | Say what specifically pays off. "The change that moves the design most". |
|
|
| `biggest unlock` | Marketing-speak. | Describe the actual change. |
|
|
|
|
### Internal jargon leaking out
|
|
Words that work in a research notebook and fail in user copy.
|
|
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `reflex defaults` | Eval-team jargon. | "Instincts", "first guesses", "default reaches". |
|
|
| `collapses into monoculture` | Eval-paper voice. | Describe what specifically went wrong (e.g. "every model picked the same three fonts"). |
|
|
| `data-driven` | Empty marketing adjective. | Cite the data. "Validated against 15 briefs across two models". |
|
|
|
|
### Marketing voice
|
|
Adjectives and verbs that gesture at quality without doing the work.
|
|
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `seamless`, `seamlessly` | Hollow positive. | Say what specifically works without friction. |
|
|
| `robust`, `robustness` | Hollow positive. | Cite the failure mode handled. |
|
|
| `elevate`, `elevates` | Marketing verb. | Use the specific verb (improve, raise, sharpen). |
|
|
| `empower`, `empowers` | Marketing verb. | "Let you", "make possible". |
|
|
| `underscore`, `underscores` | AI tell. | "Show", "make clear". |
|
|
| `pivotal` | Hollow positive. | "Central", "key", or describe the role. |
|
|
| `tapestry` | AI scenery noun. | Cut. |
|
|
|
|
### Verbs
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `delve`, `delves`, `delved`, `delving` | The most-flagged AI tell of all. | "Look at", "explore", or just delete the throat-clearing verb. |
|
|
|
|
### Throat-clearing
|
|
Sentences that delay the point. Cut them; almost nothing of value is lost.
|
|
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `in today's …` | Generic opener. | Start at the actual point. |
|
|
| `gone are the days` | Cliché opener. | Make the point directly. |
|
|
| `whether you're …` | Audience-pandering; addresses no one. | Pick one reader. Write to them. |
|
|
| `let's dive in` | Throat-clearing. | Just start. |
|
|
|
|
### Closers
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `in summary`, `in conclusion` | Restates what was just said. | End on the strongest sentence. Trust the reader. |
|
|
|
|
### Transitions
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| `moreover`, `furthermore` | Metronome transition crutch. | Drop, or use "also", or restructure. |
|
|
|
|
### Punctuation
|
|
| Banned | Why | Use instead |
|
|
|---|---|---|
|
|
| Em dash `—` (and HTML entities `—`, `—`, `—`) | Decision-avoidance: writer didn't pick a relationship between the clauses. | Comma, colon, semicolon, period, parentheses. Pick the relationship. |
|
|
| ` -- ` (double hyphen as em-dash substitute) | Worse than the em dash. Signals failed cleanup. | Real punctuation. |
|
|
|
|
## Patterns the validator can't catch
|
|
|
|
The above are the easy wins. The deeper issues require human judgment on every paragraph.
|
|
|
|
- **Negation pivot.** "It's not just X, it's Y." "Less about X, more about Y." This is now a stronger AI tell than any vocabulary item. Use sparingly. Most instances should be replaced with a direct positive claim.
|
|
- **Triadic everything.** Every list exactly three items. Every adjective in groups of three ("fast, simple, and powerful"). Vary count: use 2 or 4. Use 1.
|
|
- **The five-paragraph essay shape.** Intro → 3 sections → conclusion, on every page. Mix it up. Lead with the example. Skip the conclusion. Let some sections be one sentence.
|
|
- **Uniform paragraph length.** Insert a 4-word sentence. Insert a one-line paragraph.
|
|
- **Synthetic balance.** Pros and cons of equal length when one is clearly right. Write the recommendation; note real exceptions briefly.
|
|
- **Hollow confidence.** "Powerful" without numbers. Replace with a concrete fact.
|
|
- **Hedging stacks.** "It might potentially be useful to consider..." Each hedge is fine; stacked, they sound trained.
|
|
- **Interchangeable copy.** Swap "Impeccable" for a competitor name. If nothing becomes false, the copy is generic.
|
|
|
|
## When in doubt
|
|
|
|
Read the paragraph aloud. If you stumble, rewrite. If a sentence describes nothing specific to this product, cut it.
|