# VOICE.md — writing rules (anti-AI-slop copy)

> **Scope**: governs every word of generated copy — slide headlines and body, product UI labels and helper text, emails, descriptions, docs, commit/PR prose. Applies to all variants. The mechanical Spanish-first copy rules in `PRODUCT-UI.md` / `ANTIPATTERNS.md` (full UTF-8 diacritics, dot thousand separators `1.500`, no emojis, no exclamation-mark CTAs) still apply **on top of** everything here.
>
> **Provenance**: v1.0.3 established the base list. v2.0.0 folds in the de-slop sweeps of the IVI deck (`ivi-mid-2026`, commits `c7fe805`, `7c28f83`, `4d67bcc`, `971d05e`, `a974570`, `43fdc00`) — every rule below that cites a commit was extracted from a real before/after edit, not theorized.

Goal: text that reads like a person wrote it, not a model. The patterns below are how LLMs give themselves away. They are OFF. Default language is Spanish; English cognates are listed where the same tell crosses languages.

## Punctuation

- **Em-dash (`—`) anywhere in visible text.** Banned. Use a period, a comma, parentheses, or a line break. (Same rule as `ANTIPATTERNS.md`; repeated here because it is the single loudest AI tell.)
- **Quotes convention** (one per deck, hold it): double curly quotes `"…"` for quotes and highlighted expressions inside copy; guillemets `«…»` are **reserved for literal user queries** (the string someone types into a search box). Never keyboard-straight `"` around emphasis. *(971d05e + 22ea345: the deck oscillated, then settled on this two-level system.)*
- **Numeric ranges in visible copy**: never hyphen or dash notation (`2-3`, `18–24`). Write words (`2 o 3`) or commit to the single verified figure (`en torno a 18 meses`). Range notation is report-generator syntax — and half the time the range is not backed by the source. *(971d05e)*
- **Minus sign**: Unicode `−` (U+2212), never a hyphen. Same width as `+`, aligns delta columns. Positive deltas carry an explicit `+`.

## Banned words (Spanish)

Do not use: **ahondar, tapiz, aprovechar, utilizar, robusto, fluido, multifacético, navegar** (figurative), **optimizar, fomentar, exhaustivo, múltiples.**

Plain replacements: `usar` (not `utilizar`/`aprovechar`), `sólido`/`fiable` (not `robusto`), `explorar`/`entrar en detalle` (not `ahondar`), `mejorar` (not `optimizar` when not literally technical), `impulsar`/`apoyar` (not `fomentar`), `completo`/`a fondo` (not `exhaustivo`), `varios` (not `múltiples`).

The real fix is not synonym-swapping — it is replacing the generic word with the **concrete domain term**: `comparación exhaustiva en múltiples canales` → `comparación a fondo en varios canales`; `experiencia integrada y fluida` → `integrada, sin saltos entre canales`; `los patrones de navegación están cambiando` → `los hábitos de búsqueda están cambiando`. The concrete term proves someone thought about the sentence. *(c7fe805)*

English cognates, same ban if writing in English: *delve, tapestry, leverage, utilize, robust, seamless, multifaceted, navigate (figurative), optimize, foster, comprehensive.*

Marketing-slop verbs, also banned (ES / EN): **potenciar, desbloquear, impulsar a otro nivel, revolucionar, elevar, empoderar, transformar** (when it just means "change") / *unlock, supercharge, elevate, empower, revolutionize, game-changer.*

Two scoped exceptions:

1. **Framework jargon stays intact.** Technical labels of the client's conceptual system (GEO, JTBD, Intent Momentum) are never "humanized away" — the AI tell lives in the gloss, not the term. Humanize the explanation: `GEO · Optimización para motores generativos` → `GEO · Presencia en los motores generativos`. *(c7fe805)*
2. **The client's language wins.** If the client says «optimizar», the deck says «optimizar», banned list or not. Document the exception; do not silently drift back. *(466cdc1: the IVI cover iterated optimizar → influir → ganamos → back to «podemos optimizar» because that is the client's word.)*

## Banned constructions

- **The contrast frame «no es X, es Y» / «no solo X, sino Y»** (EN: *"it's not just X, it's Y"*). **Rationed, not sprinkled**: at most 1–2 uses per document, reserved for the core thesis. Everything else goes affirmative direct: `La web ya no es donde se elige. Es donde se confirma…` → `En la web se confirma una elección que ya se formó fuera.` If everything is defined by what it is not, the one negation that matters stops landing. *(c7fe805: 17 slides swept, two theses kept.)*
- **Negation never opens the paragraph.** When the negative nuance is worth keeping, subordinate it or move it to the end as a short closer: `No son etapas de un embudo. Son superficies…` → `Son superficies que la paciente cruza una y otra vez. Funcionan como órbitas, no como etapas de un embudo.` Closing on the negation after affirming reads human; opening on it reads generated. *(c7fe805)*
- **«Y no es solo X: es Y» as a sentence opener** — double tell (starting with Y + contrast frame). Reformulate with a concrete subject: `Y no es solo IVI: es un cambio general` → `Le pasa a todo el sector, es un cambio de comportamiento general.` *(c7fe805)*
- **«Dejamos de X y empezamos a Y»** (renunciation → action arc). Open with the action instead: `Dejamos de empujar por el funnel y empezamos a construir…` → `Construimos un sistema de gravedad alrededor de la marca y dejamos que atraiga al usuario.` *(c7fe805)*
- **Never reuse the same contrastive image twice on one screen.** If the headline says «no muestra diez enlaces», the microcopy cannot say «no diez enlaces» again — the second occurrence mutates («una recomendación, ya filtrada»). *(c7fe805)*
- **Adjective triads («X, Y y Z»).** The three-beat close is model cadence. Break it with punctuation that isolates the third element as an afterthought: `largo, caro y emocional` → `largo y caro. Y emocional.` The third term resonates instead of rounding off. *(c7fe805 + 7c28f83)*
- **Gerund chains** («midiendo…, entrando…, y adaptando…») — calqued English syntax. Convert to coordinated infinitives, `y` only before the last: `medir su intención, entrar con el rol correcto y adaptar cada mensaje`. *(c7fe805)*
- **Impersonal negative headlines («Ya no se entra a la web…»).** Put the real actor as subject, in the affirmative: `Ya no se entra a la web para informarse` → `Las usuarias se informan antes de entrar a la web`. Observational and concrete beats distant and templated. *(c7fe805)*
- **Slogan fragments after a period («Ahora hay órbitas»).** Replace with a full clause that explains the phenomenon: `El funnel ha caducado. La decisión se mueve en órbitas.` *(c7fe805)*
- **Rigid transitions**: `además, asimismo, adicionalmente, en conclusión` (EN: *moreover, furthermore, additionally, in conclusion*). Cut them or start the sentence with its actual content.
- **Filler openers**: `Espero que este mensaje te encuentre bien`, `en el vertiginoso mundo actual`, `en el ámbito de`, `cabe destacar que`, `es importante señalar que`, `vale la pena mencionar`. Delete and start with the point.
- **Chatbot throat-clearing**: `¡Buena pregunta!`, `¡Claro!`, `¡Por supuesto!`, `Sin más preámbulos`, `Dicho esto`. Never.
- **Conclusion repetition**: do not restate what you just said. Ban `en general`, `en resumen`, `para finalizar`, `en definitiva` as wrap-up signals.
- **Over-qualifying adverbs**: `realmente, verdaderamente, increíblemente, sumamente`. Usually deletable. Strong claim needs no booster.

## Headlines and labels

- **The headline must stand alone.** Eyebrows were removed from the system (v2.1.0), so the title recovers the subject the old eyebrow was carrying: `[eyebrow: la intención] No es binaria` → `La intención no es binaria`. *(a974570)*
- **Cut the prepositional tail.** Every word the context already gives is deleted. The IVI cover went from 13 to 10 words by dropping «a la web» (obvious in a deck about the web) and gaining the strong verb. *(7c28f83)*
- **Card headers anchor a noun**, never stacked adjectives: `Emocional y de alto riesgo` (emotional *what*?) → `Gran carga emocional`. *(4d67bcc)*
- **Section heads say the reading with a conjugated verb**, not an elegant nominal label: `Un laboratorio completo de decisión` → `Ocho pruebas que responden preguntas concretas`. The headline answers the reader's question; it does not decorate the section.
- **Labels name the concrete effect; a recap is called «recap».** No soft periphrasis: `Los tres planos, de un vistazo` → `Recap: los tres planos`; `El impacto directo` → `El impacto en negocio`. *(4d67bcc)*
- **Table headers and CTAs use plain first-person verbs**: `Cómo optimizamos` → `Qué hacemos`. The generic process-noun header is self-referential; the plain verb answers the client's actual question. *(c7fe805)*
- **Generated views title on the short entity name** (`target.name`), never on a long extracted field (the detected promise, the scraped headline). The human-given name is the stable identifier; a paragraph in an `<h1>` is a generated-UI tell.

## Emphasis

- **One bold per block of text, maximum.** The bold marks THE concept the audience must retain — not the flashy number. If there are two bolds, neither commands. IVI kept `<strong>antes del clic</strong>` (the thesis) and un-bolded «casi a la mitad» (the impressive figure). *(7c28f83)*
- Inside serif display headlines, emphasis is `<em>` italic + accent color, **never bold** (see `RULES.md` → Emphasis).

## Data and claims

- **Real data or nothing.** Plausible-but-invented figures, fabricated competitor lists and off-domain example keywords are the gravest AI tell in a business document. Two IVI slides were rebuilt from scratch when the real client report arrived. Pending figures use the animated `NN` placeholder (`LetterCounter`) — visible and honest — never a made-up number. *(22ea345, 16229c2)*
- **Every cited figure carries visible attribution** in the same block: `Les Binet y Peter Field · The Long and the Short of It (IPA)`. Acronyms get an asterisk footnote: `auditado SGS**` + `** SGS · Société Générale de Surveillance, certificadora independiente`. The orphan figure is the tell of the invented one. *(971d05e, 1cb6266)*
- **A claim carries its verifiable proof in the same sentence**: `Cada test cuesta unos céntimos` → `Cada test cuesta céntimos, lo comprobamos cada mes en nuestra propia factura.` Domestic evidence grounds what would otherwise read as generated marketing.
- **Declare the product's honest limit, integrated into the argument** — never as a confrontational "why we beat X" block: `Una decisión irreversible sigue mereciendo un test con personas. Gravity filtra el 80% de las dudas antes de llegar ahí.` The admitted limit buys more credibility than the absolute claim.
- **The chart caption says the reading, not the metric name**: `Visibilidad media de IVI` → `Quién sale nombrado en la respuesta`. The KPI's technical name moves to the secondary meta-line. *(22ea345)*
- **The headline does not verbalize what the chart already shows.** The dramatic figure lives on exactly one surface. IVI cut «Y en 2 de cada 3, no aparecemos» from a title because the chart's brace already said it. *(800b9e3)*
- **Number formatting is es-ES and centralized** (one `format.ts`): thousands with dot (`4.052`), decimals with comma (`12,7`), abbreviate with the word `mil` — never `K`. Approximation is `~` in chart copy and `unas / unos` in `aria-label` prose.

## Rhythm

- **Vary sentence length.** Mix short, medium, and long in the same paragraph. Fragments are allowed. A three-word sentence can land harder than a clause-stacked one.
- Uniform sentence length is the rhythm of a machine. Read it aloud; if every sentence has the same cadence, break one.
- **One idea per line.** In leads, two distinct ideas separate with an explicit `<br />` rather than running on; in table cells, two actions are two lines, not a semicolon. The visual cut marks the reading rhythm of a projected screen. *(4d67bcc, cbe9a0b)*

## Register and audience

- **Grammatical gender calibrated per section by the real audience**, not by the model's default: IVI uses «el usuario» in theory sections, «la usuaria» on the cover, «la paciente» in the client-specific planes. Iterate until it matches who is actually in the room. *(971d05e, 466cdc1)*
- **The brand metaphor is concentrated in one passage**, not sprinkled through every section. A metaphor repeated per-paragraph is the LLM decorating the theme.
- **Utilitarian pages get zero rhetoric.** The IVI login went from eyebrow + dramatic title («Esto es a puerta cerrada.») + lead to a single instruction and the field. Excess voice on a functional screen is a generation tell. *(43fdc00)*
- **Status and error microcopy is plain sentences ending in a period**, spoken by the control itself: the button label declares its state (`Entrar` → `Comprobando…`), the error says what happened (`La contraseña no es correcta.`). Never `¡Ups! Algo salió mal`, never spinner + generic toast.

## Format

- **No bullet lists in an informal email or a prose description.** Write in flowing sentences. Reserve bullets for genuinely enumerable, scannable data (specs, steps, option lists), not for ideas that belong in a paragraph.
- **No section headings on short copy.** A two-paragraph note does not need an `## Overview`.
- **No bold-the-first-words-of-every-bullet** tic when a plain sentence does the job.

## Voice

- Write like a person, not a brand voice generator. Natural register over stiff officialese. Where Spanish allows a contraction (`del`, `al`) use it; do not inflate into bureaucratic forms.
- Perfect, voiceless grammar reads as machine output. A little asymmetry, a direct address, a short reaction — that reads human.
- Commit to a point of view. Hedging stacks (`podría`, `tal vez`, `en cierto modo`, `hasta cierto punto` piled together) signal a model covering itself.
- Title-case headings everywhere (EN) — banned. Sentence case.

## Pre-ship checklist (run on every block of copy)

1. Any `—` in visible text? Replace it.
2. Any banned word from the list above? Swap for the concrete domain term, not just a synonym.
3. Count the contrast frames («no es X, es Y»). More than the 1–2 thesis uses? Rewrite the rest affirmative.
4. Does any paragraph open with a negation? Subordinate it or move it to the close.
5. Did a list land on exactly three items by reflex? Check it earns three; break the triad if not.
6. More than one bold in a block? Keep the concept, drop the rest.
7. Any figure without visible attribution? Source it or cut it. Any range like «2-3»? Words or one number.
8. Do three sentences in a row have the same length? Break one.
9. Does it open with filler or close with a summary of itself? Delete both.
10. Read it aloud. Would a person say it this way, or only a model? If only a model, rewrite.