brand-voice

brand-voice — define and hold the verbal identity

Part of super-ux — see system-map.md for the whole pipeline. After changes, run python3 docs/brand/lint.py.

docs/ux/ decides what the product does. This skill decides how it speaks, and owns docs/brand/ in the target project.

Format contract: brand-contract.md (brand-contract v1). Read it before writing or editing anything under docs/brand/. Never deviate from its file names, field names or statuses — the linter and the audit key off them.

The pack library: voice-packs.md — six archetypes, each with a declared failure mode. The register model: surface-registers.md. Locales: localization.md.

Invoked with no task → status, then one next action

1. Report the state: is a pack recorded, what voice.md says its Status is, how many facts carry ⚠ TBD or no source, locale parity, and the linter's error and warning counts.
2. Name every unresolved fact. Never invent one to close a gap — an unknown is reported, not filled.
3. Propose exactly one next action, usually the top open fact or the surface the user actually came for.

Where the voice comes from

The pack is derived from docs/ux/foundation.md — personas, jobs, and the deciding input: what the user loses when the product fails. A voice that charms when the stakes are a playlist is intolerable when the stakes are payroll.

The dependency runs one way. A persona never changes because a tone was appealing. With no foundation, work in degraded mode: stamp Derived-from: inferred, say plainly that the WHY layer should be built, and continue rather than blocking.

The route itself has a spoken opt-out: an operator saying "no brand" / «без бренда» declines it — proceed without the pack and say so, rather than dropping it silently.

Choosing a workflow

Announce which one you are running.

Init

1. Read the foundation. Personas, JTBD, journeys, stakes. Where it is absent, interview: who is this for, what are they accountable for, what does failure cost them.
2. Read what already exists. Interface strings, landing copy, README, store listing, recent posts. The current voice is data even when nobody chose it.
3. Propose one pack with reasoning, plus one alternative. Name why the runner-up loses. Let the user pick.
4. Seed docs/brand/ from this skill's own templates/brand/, and fill the Sources: block first — nothing else can be checked until the linter knows where the project keeps its text.
5. Inventory sweep for strings.md: routes, screens, buttons, states, errors, empty states. Every string gets a row with its file:line and the scenario it serves. For a large codebase, use available read-only subagents in parallel, one area each; without delegation, inspect the same areas sequentially and keep the same evidence requirements.
6. Ask which humanization pass this project wants, and write the answer to voice.md's Humanization pass: field. own is the default and the only one that reads this pack's registers and facts; npx sshlg-skills humanizers shows what else is installed and how to install what is not. Ask once — the field exists so nobody is asked twice, and it selects a pass, never a verdict.
7. Everything starts Status: draft.

Calibrate

The pack is a starting position; this is where it becomes the product's own.

• Terminology. Which generic words does this product replace, and with what. Seed the banned table from weak verbs, hedging chains and ai-tells.md, then add what is specific here.
• Facts. Every number the product quotes, with a source, a checked date and a review date. Mark internal figures Public: no.
• Channels. One record per surface the product actually has. Register as deltas; Forbidden: always carries both the physics and the brand half.
• Ready lines. Six to ten, written for this product, not copied from the pack.
• Failure mode. Copy the pack's into voice.md so the audit can look for it by name.

Present section by section for approval. Approved moves draft → validated.

Update

1. Identify what changed — positioning, a persona, a price, a tier name, a new surface.
2. Apply the edits. A changed entity name propagates to terminology.md, strings.md and every locale in the same change.
3. Changed files drop to Status: draft until re-approved.
4. Re-stamp Last calibrated.

Validate

1. Integrity — every field the contract requires is present; statuses are legal; Derived-from resolves against the foundation.
2. Coverage — every surface the product ships has a record; every locale declared has a file; every quoted number has a fact.
3. Consistency — run python3 docs/brand/lint.py and fold its findings in. It proves the mechanical half; report what it cannot see as questions for /ux-audit copy.
4. Staleness — foundation newer than the last calibration, facts past review, physics rules past their checked date.

Definition of done

• Contract honored; the marker on every file.
• The user has seen and approved new or changed sections.
• python3 docs/brand/lint.py exits 0, or every remaining finding is reported with a reason.
• Unknowns stated as unknowns. Nothing invented to make a table look full.

What else is in references/. This skill names 6 contract(s) directly; references/ holds 13, because a contract this skill names links others and the whole closure ships inside the skill — the skills CLI installs one directory and a sibling's file would arrive dangling. Open the ones named here; the rest are reached from them, by name, when a contract sends you.