ssheleg/super-ux / plugins/super-ux/skills/brand-voice
brand-voice
VerifiedUse when defining or checking how a product speaks: tone of voice, terminology, canonical facts, register. Triggers: "tone of voice" / "тон оф войс", "brand voice" / "голос бренда", "брендбук", "наша терминология". Not for writing the text (copywriting). Refusal phrase "no brand" / «без бренда».
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| references/ai-tells.md | markdown | 20.6 KB |
| references/brand-contract.md | markdown | 25.4 KB |
| references/channel-playbooks.md | markdown | 20.0 KB |
| references/hooks.md | markdown | 26.4 KB |
| references/localization.md | markdown | 5.2 KB |
| references/marketing-copy.md | markdown | 8.1 KB |
| references/research-outliers.md | markdown | 5.4 KB |
| references/seo-aeo-safety.md | markdown | 9.9 KB |
| references/store-copy.md | markdown | 7.4 KB |
| references/surface-registers.md | markdown | 9.1 KB |
| references/system-map.md | markdown | 12.4 KB |
| references/video-script.md | markdown | 14.6 KB |
| references/voice-packs.md | markdown | 15.9 KB |
| templates/brand/README.md | markdown | 2.3 KB |
| templates/brand/channels.md | markdown | 4.2 KB |
| templates/brand/copy-brief.md | markdown | 187 B |
| templates/brand/facts.md | markdown | 1.3 KB |
| templates/brand/locale.md | markdown | 2.2 KB |
| templates/brand/strings.md | markdown | 1.7 KB |
| templates/brand/terminology.md | markdown | 1.2 KB |
| templates/brand/voice.md | markdown | 2.2 KB |
references/ai-tells.md
View on GitHub# Machine-drafting markers: detect, fix, and know when to stop
Text drafted by a model has measurable habits. This file names them, grades
them, and bounds the repair, because an unbounded "make it sound human" pass
destroys meaning while improving rhythm.
## Contents
- [Severity](#severity)
- [Naturalness grade, applied to the result](#naturalness-grade-applied-to-the-result)
- [The markers](#the-markers)
- [The dash rule in full](#the-dash-rule-in-full)
- [Density threshold](#density-threshold)
- [The change-rate guard](#the-change-rate-guard)
- [Semantic-preservation check, mandatory before output](#semantic-preservation-check-mandatory-before-output)
- [What "human" is not](#what-human-is-not)
Used by the `Humanize` mode of `copywriting` and by `B060`, `B062`, `B063`,
`B066` and `B067` in `brand_lint.py`. Voice, once the generic is gone, comes from
[voice-packs.md](voice-packs.md) via the project's `voice.md`.
Every marker carries an id. A rule set that cannot be enumerated cannot have
coverage computed over it, and four of these are now mechanical checks whose
ids are how the linter and the doctrine stay pointed at the same thing.
## Severity
| Grade | Meaning |
|---|---|
| **S1** | decisive on its own, so one instance reads as machine-drafted |
| **S2** | one or two are fine; three or more is a signal |
| **S3** | weak alone, decisive when stacked with others |
`B060` is **advisory: it WARNS, it never errors and never gates.** A count of markers is a signal to a writer, not a verdict on authorship — three S1 markers no more prove a machine wrote the text than two prove a person did, and the false positives fall hardest on someone writing in a second language. The severity above ranks how much ONE marker suggests, so a writer knows which to look at first; it is not a threshold that fails a text.
## Naturalness grade, applied to the result
After the rewrite, not the input. **The grade is advisory — a reading of how
many traces remain, never a claim that a person or a machine wrote it, and never
a gate.** It describes the RESULT so a writer can decide whether another pass is
worth it; it decides nothing on its own.
- **A**: no S1, at most two S2. Few traces.
- **B**: one or two S1, or three to five S2. Minor traces.
- **C**: three or more S1, or six or more S2. Traces are obvious; another pass
may be worth it.
- **D**: traces across several categories, or the change-rate guard fired.
**A quote, a registered domain term, and an explicit `Humanization: off` do NOT
force a rewrite.** A marker inside quoted material is the source's word, not the
writer's; a term the brand registered is meant to recur; and `off` (with its
recorded reason) preserves the text exactly. None of the three lowers the grade
into a demand to change what the writer chose. **Brand bans are a separate user
policy**, not an AI-tell: a word the brand forbids is the brand's decision, in
`terminology.md`, and belongs to that check — not to this one.
## The markers
| id | Marker | Grade | Checked by |
|---|---|---|---|
| AT-01 | Vocabulary | S1 | `B060` |
| AT-02 | Hedging chains | S1 | `B060` |
| AT-03 | Uniform sentence length | S1 | judgement |
| AT-04 | Identical paragraph shape | S1 | judgement |
| AT-05 | Vagueness where a fact belongs | S1 | `B030` from the other side |
| AT-06 | The em dash and the rhetorical dash (a hard ban, not a count) | S1 | `B062`, `B067` |
| AT-07 | A title that ends in a full stop | S1 | `B026`, `B063` |
| AT-08 | The rule-of-three habit | S2 | judgement |
| AT-09 | False balance | S2 | judgement |
| AT-10 | The summary conclusion | S2 | judgement |
| AT-11 | "Not just X, but Y" | S2 | judgement |
| AT-12 | The bold reflex | S2 | judgement |
| AT-13 | The colon hook | S2 | judgement |
| AT-14 | Symmetrical headings | S3 | judgement |
| AT-15 | Over-signposting | S3 | judgement |
| AT-16 | Invisible characters | S2 | `B066` |
### AT-01. Vocabulary, S1
`delve`, `landscape` (figurative), `crucial`, `vital`, `pivotal`,
`leverage` (as a verb), `robust`, `comprehensive`, `holistic`, `foster`,
`facilitate`, `navigate` (figurative), `seamless`, `tapestry`, `realm`,
`testament to`, `underscores`, `it's worth noting`.
Never simply delete: replace with the thing the word was standing in for.
`robust` becomes the number. `facilitate` becomes `help`. `crucial` becomes
the consequence, stated, so the importance is self-evident.
### AT-02. Hedging chains, S1
"It is important to note that", "It is worth mentioning that", "One might
argue that", "In many cases", "It goes without saying", "Needless to say".
These exist because the drafting process is uncertain and hedges by default.
A person hedges when they are actually uncertain, which is much less often.
### AT-03. Uniform sentence length, S1
Every sentence 18 to 22 words. The most reliable tell and the least noticed,
because no individual sentence is wrong.
The fix is rhythm, not vocabulary: break long sentences, let a short one land
after a long one, use a fragment where it serves emphasis, and let one
sentence run when the thought genuinely needs the room.
### AT-04. Identical paragraph shape, S1
Statement, explanation, example, bridge, every paragraph, forever. Real
writing varies: a one-sentence paragraph, a question answered immediately, a
short list dropped into prose, an aside, a correction.
### AT-05. Vagueness where a fact belongs, S1
"Many companies", "studies show", "significantly improved", "leading
brands", "a lot of". Each is a place where a specific claim was avoided
because a specific claim can be checked.
Replace with the real figure from `facts.md`, or say plainly that you do not
have one. Honest absence beats confident vagueness, and it is also the
`B030` rule from the other side.
### AT-06. The em dash and the rhetorical dash, S1, a hard ban
**Newly authored text carries no em dash (U+2014), in any language** (owner
decision, 2026-10-18). This marker is not advisory and not a density target:
one instance in text you wrote is a defect to fix before delivery. The same
rule is always on in every host the family writes to, so it binds chat
answers, messages, mail, reports and handoffs as well as product copy.
The rhetorical dash is banned in all of its spellings: an em dash, an en dash,
`--`, or a hyphen with a space each side, wherever it stands in for a full
stop, a comma or a colon. Rewrite with one of those marks or brackets, or
restructure the sentence. The rare exception is a dash Russian grammar
requires where no rewrite reads naturally. The character stays only inside an
exact quotation, code, a command, a path or a historical record. See
[the dash rule in full](#the-dash-rule-in-full): choosing the replacement is
the work, and a find-and-replace picks the wrong mark.
### AT-07. A title that ends in a full stop, S1
A heading, a label, a button, a menu item, a page title, a store title, a
subject line: each is a name, not a statement, so it takes no terminal
punctuation. A question mark is fine where the title genuinely asks. An
ellipsis is fine where the control genuinely opens something further.
A decorative full stop is a copy-policy defect, not proof of who wrote the
text. `B026` catches it in registered labels; `B063` checks document titles,
Markdown headings and HTML h1–h6 in declared marketing/store sources. Nested
inline tags, entities and `<br>` fragments keep their heading role. Splitting
“Your agents. Your tools.” into sentences does not exempt a heading.
Keep questions, ellipses, abbreviations such as `etc.`, versions and URLs.
Ordinary paragraph sentences keep their punctuation. Hero summaries and
captions are a project's explicit display-copy policy, not a global ban on
punctuation anywhere above the fold.
Inspect the rendered surface and its generator. A flat prose export can erase
heading roles; declare the HTML or retain Markdown heading markers. Static HTML
checks ignore scripts, templates, attributes and visibly hidden source elements;
`aria-hidden` alone is not visually hidden. External CSS and runtime-generated
text require browser review. Make a required title rule block with `--fail-on
B063`; an advisory exit zero does not prove that the title rule was checked.
### AT-08. The rule-of-three habit, S2
Three adjectives, three examples, three-item lists, everywhere. Three is a
good number sometimes; it is not a good number always.
### AT-09. False balance, S2
"While X has advantages, Y also has merits" as a way of avoiding a position.
If the piece has a view, state it.
### AT-10. The summary conclusion, S2
"In conclusion, we explored X, Y and Z. By implementing these strategies…"
A restatement of the introduction. A real ending either adds something or
stops.
### AT-11. "Not just X, but Y", S2
Also "it's not about X, it's about Y", and in Russian «не просто X, а Y».
The construction is legitimate and common in real writing. The tell is the
reflex: it appears whenever the draft needs to sound insightful and has no
new fact to offer, so the sentence pivots on a contrast the reader was never
holding.
The test is whether anyone actually believed X. If nobody did, the sentence
is refuting a position it invented, and the fix is to delete the first half
and keep Y.
### AT-12. The bold reflex, S2
Every second phrase bolded, so the emphasis marks nothing. Bold is a claim
that this is the part to read first; four claims per paragraph is no claim.
The fix is a budget rather than a ban. One bolded span per paragraph at most,
and only where a reader skimming the page would need exactly that phrase.
Lists of bolded lead-ins are the one place density is fine, because there the
bold is structure and not emphasis.
### AT-13. The colon hook, S2
"Here's the thing:", "The result?", "But here's what most people miss:",
«И вот в чём дело:». A fragment that promises a revelation, then delivers an
ordinary sentence. It is the written form of a pause for effect, and it works
about once per piece.
Related and worse: the one-line paragraph used as a drumbeat, three or four
of them in a row, each landing a supposed insight. That rhythm is the most
recognisable shape of generated marketing prose in 2026.
### AT-14. Symmetrical headings, S3
Every heading the same grammatical shape and roughly the same length.
### AT-15. Over-signposting, S3
"First, let's look at…", "Now that we've covered…", "Let's dive into…".
Structure the reader can see does not need narrating.
### AT-16. Invisible characters, S2
Zero-width spaces and joiners, a word joiner, a byte-order mark in mid-text, a
soft hyphen, direction marks and overrides, tag characters, and the
look-alike spaces (no-break, narrow no-break, thin, figure, em and en space).
They render as nothing or as an ordinary space, survive every paste, and break
search, hyphenation and exact-match checks downstream; text pasted out of a
chat window often carries them. **A fingerprint of the pipeline, not proof of
authorship**, so S2 and advisory: `B066` warns, names the code point and its
line, and rewrites nothing.
The eighteen named classes are the ones the humanizer in
`Jakeschincariol/instagram-agent-skill` strips
([`skills/ig-human/slop.json`](https://github.com/Jakeschincariol/instagram-agent-skill/blob/d03c56bb598be770c60b201f94237e5d1a4268a6/skills/ig-human/slop.json),
MIT, read 2026-10-07): U+200B, U+200C, U+200D, U+2060, U+FEFF, U+00AD,
U+180E, U+061C, U+200E, U+200F, U+2063, the tag block U+E0000–U+E007F, and
U+00A0, U+202F, U+2009, U+2007, U+2003, U+2002. Any other Unicode format
character (category `Cf`: bidi embeddings, overrides and isolates among them)
is reported by the same check.
**What this marker does not take from that humanizer:** its typography pass,
which turns an em dash into a comma, an en dash into a hyphen and curly quotes
into straight ones. In Russian the dash is normative and «ёлочки» are the
quotation marks; the rhetorical dash is AT-06, which knows the difference.
Every class has a context where it is correct, and those contexts are numbered
so that each has a fixture asserting silence:
- **`AT-16-E1`** A zero-width joiner inside an emoji sequence: it is part of
the emoji (a family emoji is three people joined by two of them).
- **`AT-16-E2`** A joiner or non-joiner beside a letter of a script that spells
with it: Persian, Arabic, the Indic scripts.
- **`AT-16-E3`** A direction mark or isolate in text that carries
right-to-left letters. Embeddings and overrides (U+202A–U+202E) stay
reported even there: isolates replaced them, and an override is the
mechanism of the "Trojan Source" attack.
- **`AT-16-E4`** Tag characters inside a flag sequence (🏴 plus tags plus
U+E007F, as in the flag of England).
- **`AT-16-E5`** A no-break or narrow space in a locale whose typography puts
one there: Russian, Ukrainian, Belarusian, French (from the document's
`locale`, the pack's primary locale, or Cyrillic in the text).
- **`AT-16-E6`** Dashes and quotation marks: never examined by this marker, in
any language.
- **`AT-16-E7`** A byte-order mark as the first character of a file: the
file's encoding signature, not text.
`B066` reads the raw source files, so an HTML entity such as ` `, which
someone typed on purpose, is not reported; a literal character is.
## The dash rule in full
Two layers, and the first one is absolute.
**The glyph.** Newly authored text carries no em dash (U+2014) in any
language (owner decision, 2026-10-18). Existing text you are not rewriting,
exact quotations, code, commands, paths and historical records keep theirs.
**The role.** Under that, the dash is banned where it is **rhetorical** and
allowed where it is **grammatical** and unavoidable. A pass that strips every
dash produces ungrammatical Russian, and a pass that keeps them produces the
tone this file exists to remove. So the Russian dash survives only where the
grammar needs it and no rewrite reads naturally; where a colon, a comma or a
reordered clause reads as well, the rewrite wins.
**The rule is about the mark's role, not its spelling.** An em dash, an en
dash and a hyphen with a space each side are the same mark doing the same
job, so exchanging one for another changes nothing the rule cares about.
This is the likeliest way a draft appears to be fixed and is not: a
find-and-replace can reach the glyph and cannot reach the habit. Measured on
trycomp.ai, 2026-08-30: twenty rhetorical dashes on one page and not one em
dash among them, every one written as a spaced hyphen
(`docs/research/landings/trycomp.md`).
**Rhetorical, and out.** The dash is doing a job that punctuation already has
a mark for:
| Written | Standing in for | Fix |
|---|---|---|
| "It works — and it works fast" | a comma | "It works, and it works fast" |
| "One thing matters — speed" | a colon | "One thing matters: speed" |
| "He left — it was too late" | a full stop | "He left. It was too late" |
| "The result — which nobody predicted — was…" | brackets or commas | "The result, which nobody predicted, was…" |
**Grammatical, and allowed only where unavoidable.** The language requires the
mark, so the linter never errors on it; whether a rewrite reads as naturally is
the writer's call, made each time rather than assumed:
Each carries an id, because an exemption is a promise the code has to keep and
an unnumbered promise cannot have coverage computed over it. `AT-06-E1` was
implemented from the start; `AT-06-E4` was written here in v0.39.0 and
implemented in v0.52.0, thirteen days in which this file and the linter
disagreed and only this file said so.
- **`AT-06-E1`** The Russian and Ukrainian copula, where the verb is absent by
rule: «Москва — столица». English has no equivalent, which is why a global
ban reads as reasonable in English and breaks Russian on the first line.
Never a `B062` error; `B067` warns on it, because the copula is allowed only
where no rewrite («Столица России: Москва», «Москва стала столицей») reads
as naturally.
- **`AT-06-E2`** Numeric and page ranges, written with an en dash (U+2013):
«2020–2024», «с. 15–20». A range is never rhetorical, but an em dash joining
one is the glyph the first layer bans, so `B067` errors on «2020—2024» and
is silent on the en dash.
- **`AT-06-E3`** Direct speech in the Russian convention: «— Привет, — сказал
он».
- **`AT-06-E4`** A dash alone in a table cell, standing for "no value". It is a
glyph doing the job of an empty string, not punctuation joining two clauses.
In a new table write an en dash or "n/a"; the linter leaves an existing
cell alone.
Every one of them has a fixture asserting **silence**, named after its id, and
`validate_ai_tell_coverage` refuses an exemption without one. A positive
fixture proves a rule fires; only a negative one proves an exemption survives
the next person widening the rule.
**Choosing the replacement is the work, and it is not mechanical.** The full
stop, the comma and the colon carry three different relationships between the
halves of the sentence. A comma joins, a colon promises that the second half
explains the first, a full stop says they are separate thoughts. Substituting
the wrong one damages the text more than the dash did, so the replacement is
chosen from the meaning, never by find-and-replace.
Where the two halves genuinely need no relationship stated, the strongest fix
is usually the full stop, because a dash is most often reached for to avoid
committing to one.
**What the linter proves and what it cannot.** `B062` reduces every spelling
of the mark to one before it judges anything, so swapping the glyph does not
clear a finding, and a dash alone in a table cell is blanked first because it
is standing for an empty string rather than joining two clauses. It then
errors on the patterns that can be established without parsing grammar: a
dash followed by a coordinating conjunction, which is always a comma's job,
and paired dashes bracketing an aside inside one sentence. In a locale with no grammatical
dash, it errors on every dash that is not a range or direct speech, which is
the rule stated above. In a locale that has one, it cannot separate the
copula from the rhetorical remainder without a parser. `B067` covers the
glyph those branches pass over: it errors on an em dash joining a range and
on an em dash opening a line where the locale has no dialogue dash, and it
warns on every lone dash in a locale with a grammatical one, so the writer
decides each time whether the grammar needs it. A check that claimed to know
the difference would be asserting what it has not measured.
## Density threshold
Above roughly **ten markers per 500 words**, editing does not work. The
result of polishing a piece that is mostly patterns is the same patterns with
better words. Say so and rewrite from the argument instead. That judgement is
part of the job, not a failure of it.
## The change-rate guard
After rewriting, estimate the proportion of the text that actually changed,
counting meaning-bearing changes and not punctuation or spacing.
| Change rate | Action |
|---|---|
| under 30% | ship it |
| 30 to 50% | ship it, and say the rate out loud |
| **over 50%** | **do not ship.** Report the rate and ask. |
Above half, this is no longer an edit. It may be the right rewrite, but that
is a decision with an owner, and quietly replacing someone's text while
calling it a polish is how meaning gets lost without anyone noticing.
Dash removal is the case most likely to breach the guard while looking
harmless, because it touches many lines and each touch is small. Punctuation
alone does not count toward the rate; a clause reordered to lose its dash
does.
## Semantic-preservation check, mandatory before output
Every one of these, every time. A failure means fix and re-check, not note
and proceed.
- [ ] Every number, date, currency and proper noun preserved exactly
- [ ] Causal direction unchanged, so no "X because Y" turned into "Y because X"
- [ ] No negation inverted: can/cannot, will/will not, is/is not
- [ ] Direct quotations untouched, inside their quotation marks
- [ ] The core claim and the conclusion unchanged
- [ ] Register and formality consistent with `voice.md`, not drifted upward
- [ ] Every remaining factual claim still traceable to `facts.md`
- [ ] Every dash removal re-read in place, because the replacement mark
changes the relationship between the two halves
## What "human" is not
Not typos. Not slang. Not deliberate roughness. The target is a person who
writes well: someone with a position, specific knowledge, and a reason to
have written this. Add friction only where a real writer would have it, such
as a correction mid-thought, an admission of uncertainty, or an aside that
shows they know more than the paragraph needed.
And a piece that already reads naturally gets left alone. Editing text that
is fine to prove the pass ran is the failure mode of this whole activity.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |