@damiangilgonzalez/harness 1.3.7

package/skills/brand-voice/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: brand-voice
+description: "Use when defining how a brand SOUNDS as a reusable system: adjectives turned into linguistic rules, four tone dimensions as ratios, a use/avoid word bank, an AI voice-DNA block — so content stops sounding like five different writers. NOT the finished copy written against it (that is `landing-copy` / `marketing`), NOT the brand's look (`brand-identity`)."
+tags: [brand-voice, tone-of-voice, messaging, brand, voice-guide]
+recommends: [landing-copy, brand-identity, marketing, content-engine, customer-support]
+origin: risco
+---
+
+# Brand Voice — How the Brand Sounds
+
+You own the **reusable voice-and-tone system**: 3–5 personality traits → concrete linguistic rules → a position on the four tone dimensions → a use/avoid word bank → a tone-by-context matrix → a paste-into-the-prompt voice-DNA block. The output is a persisted document, never a finished piece of copy.
+
+The line: **brand-voice owns the reusable definition of how the brand sounds.** The moment you write one finished piece against it, that is a copywriting skill — page hero/value prop/CTA is `landing-copy`; launch emails and channel posts are [`../marketing/SKILL.md`](../marketing/SKILL.md); blog and article systems are `content-engine`, `article-writing`, `newsletter`, `social-publisher`; an investor narrative is [`../pitch-deck/SKILL.md`](../pitch-deck/SKILL.md); a live customer ticket is `customer-support` (it consumes this guide, it does not author it). The way the brand *looks* — logo, color, type, design tokens — is `brand-identity`, and layout/motion is [`../design/SKILL.md`](../design/SKILL.md).
+
+## Voice vs. tone (the load-bearing distinction)
+
+**Voice is constant; tone flexes by context.** Voice is the brand's fixed personality across everything it writes. Tone is the local adjustment for the reader's emotional state and the topic's sensitivity. A frustrated user does not want a joke; a celebration screen does not read like a financial disclosure — yet both are the same voice. (Nielsen Norman Group, "The Four Dimensions of Tone of Voice," pub. 2016-07-17, updated 2023-08-16.)
+
+Why it matters: you author **one** voice and apply **many** tones. Conflate them and you get a guide that says "be playful" on a fraud-alert page — unusable. The guide locks voice once and tabulates tone per context (Step 5).
+
+Why bother at all: consistent brand presentation correlates with revenue uplift — ~23% average, up to ~33% at the upper range across 1,800 brands in 14 industries (Lucidpress/Marq, "State of Brand Consistency"). Treat it as calibration for the effort, not a causal promise — it is a correlational study.
+
+## The flow (six steps)
+
+```text
+1 Traits (3–5)  →  2 Rules (Bad→Good)  →  3 Four dimensions (ratios)
+       →  4 Word bank (use/ban)  →  5 Tone-by-context matrix
+              →  6 AI voice-DNA block  →  persist + audit
+```
+
+### Step 1 — Traits (pick 3–5)
+
+Distill the brand to **3–5 adjectives**. Fewer than 3 is not a personality; more than 5 is unmemorable and nobody applies them. (Sprout Social brand-voice guide; Inkbot Design brand-voice chart.)
+
+Reject brand-neutral adjectives. If a competitor would never claim the *opposite*, the word is filler and says nothing. "Innovative," "passionate," "customer-focused," "cutting-edge" — no brand claims "stagnant" or "indifferent," so these traits exclude nothing.
+
+Each trait gets a one-line **this means / this does not mean**, so it is testable:
+
+```text
+Plain-spoken
+  this means:        we say "we fixed it" — short Anglo-Saxon words, no hedging
+  this does NOT mean: dumbed-down or curt; we still explain the why
+Quietly confident
+  this means:        we state the benefit and stop; no exclamation marks
+  this does NOT mean: arrogant, or making claims we can't back with proof
+```
+
+### Step 2 — Rules (each trait → 2–3 linguistic rules)
+
+Vague directives fail, especially for an LLM: "be professional" produces nothing reproducible. Voice only transfers when quantified into linguistic rules. (Search Engine Land, "How to train in-house LLMs on brand voice," 2025; Fishtank, "Train Generative AI to Speak in Your Brand Voice," 2025.)
+
+Per trait, write 2–3 rules across these levers — **person, sentence-length ceiling, active vs. passive, contractions, jargon policy** — and show one Bad→Good rewrite per cluster:
+
+```text
+Trait: Plain-spoken
+  R1  Active voice. Subject does the verb.
+  R2  Sentence ceiling ~20 words; break anything longer.
+  R3  Jargon only when defined in-line on first use.
+
+  Bad : "Optimal outcomes are facilitated through the leveraging of our
+         platform's robust capabilities."  (passive, 12-word abstraction, banned words)
+  Good: "Our platform does the heavy lifting so your team ships faster."
+```
+
+```text
+Trait: Quietly confident
+  R1  First person plural ("we"), second person for the reader ("you").
+  R2  Use contractions ("we're", "you'll") — formal-but-human, not stiff.
+  R3  Zero exclamation marks; the claim carries the energy.
+
+  Bad : "We are SO excited to announce our amazing new feature!!!"
+  Good: "New: branch previews ship with every PR. No config."
+```
+
+### Step 3 — Plot the four dimensions (decision table)
+
+Tone of voice is measurable on four sliding scales, not switches. (Nielsen Norman Group, same article.) Pick a position on each as a **ratio**, not "somewhere in the middle" — a ratio forces a defensible choice. (Sprinklr / Bigeye brand-voice frameworks, 2025.) A financial brand might run 80/20 formal; a fitness app 30/70 serious-vs-playful.
+
+This branches per brand, so the table earns its place:
+
+| Dimension | Position (ratio) | Why this brand sits here |
+|---|---|---|
+| Formal ↔ Casual | 65 / 35 casual | Buyers are technical and busy; warmth without slang. |
+| Serious ↔ Funny | 80 / 20 serious | We handle money/data; humor only in low-stakes moments. |
+| Respectful ↔ Irreverent | 70 / 30 respectful | We challenge category clichés, never the reader. |
+| Matter-of-fact ↔ Enthusiastic | 60 / 40 matter-of-fact | Proof over hype; energy lives in verbs, not adjectives. |
+
+Fill the ratios from the traits, not from taste. If a ratio contradicts a trait, one of them is wrong — reconcile before moving on.
+
+### Step 4 — Word bank
+
+Two lists. Power words and a ban list. (Oxford College of Marketing, "AI Brand Voice Guidelines," 2025-08-04.)
+
+- **Power words (15–20):** the vocabulary the brand leans on, derived from the traits. "Plain-spoken + confident" → ship, fix, build, fast, clear, done, plain, real, works. Not a thesaurus dump — words a human would recognize as *this* brand.
+- **Ban list (the drift killer):** corporate filler and AI tells. This list is what stops off-brand drift and the generated-by-a-bot smell. Starter set: `leverage`, `seamless`, `elevate`, `delve`, `robust`, `unlock`, `game-changer`, `in today's fast-paced world`, `revolutionize`, `synergy`, `cutting-edge`, `best-in-class`. Add brand-specific bans (e.g. never say "users," say "teams").
+
+The full starter ban list and the method for deriving power words from traits live in [`references/word-bank.md`](references/word-bank.md).
+
+### Step 5 — Tone-by-context matrix
+
+Voice stays fixed (the row content proves it); tone shifts per context. Build the matrix so writers and the LLM know which dial to turn where:
+
+| Context | Voice (constant) | Tone shift | Example line |
+|---|---|---|---|
+| Onboarding | plain-spoken, confident | warm, encouraging | "You're in. Let's connect your first repo." |
+| Error / failure | plain-spoken, confident | plain, reassuring, zero humor | "That upload failed. Your data is safe — try again." |
+| Success / celebration | plain-spoken, confident | a little warmth, still no hype | "Done. Your preview is live." |
+| Billing / account | plain-spoken, confident | precise, calm, no jokes | "Your plan renews June 30. Cancel anytime, no fees." |
+| Legal / security notice | plain-spoken, confident | formal, exact, literal | "We encrypt data in transit and at rest. See our DPA." |
+
+The voice column never changes line to line — that is the whole point. Only the tone column moves.
+
+### Step 6 — The AI voice-DNA block
+
+Assemble the guide into one paste-into-a-system-prompt block so an LLM (or any writer) reproduces the brand. Concrete rules + lexicon, never adjectives alone:
+
+```text
+VOICE DNA — <brand>
+Traits: plain-spoken, quietly confident, technical-but-human.
+Rules: active voice; sentences <=20 words; use contractions; first person
+  plural "we", reader as "you"; no exclamation marks; jargon only if defined.
+Dimensions: 65/35 casual, 80/20 serious, 70/30 respectful, 60/40 matter-of-fact.
+Use: ship, fix, build, fast, clear, real, works, plain.
+Never use: leverage, seamless, elevate, delve, robust, unlock, game-changer,
+  "in today's fast-paced world", revolutionize, synergy, best-in-class.
+Tone by context: onboarding=warm; error=plain+reassuring, no humor;
+  success=light warmth, no hype; billing=precise+calm; legal=formal+exact.
+```
+
+**Persist it.** Write the compiled guide under `docs/wiki/brand/voice-guide.md` and the voice-DNA block beside it, per the `harness` Karpathy-wiki convention (compiled brand articles under `docs/wiki/brand/`, raw user inputs under `docs/raw/brand/`). The persisted file is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:` (use `type: brand-voice`) — see the frontmatter block in [`references/voice-guide-template.md`](references/voice-guide-template.md), which is also the fill-in-the-blanks skeleton for the whole guide (traits → rules → 4-D ratios → word bank → context matrix → voice-DNA block) with one fully worked mini-example brand. This is the exact study `marketing`, `landing-copy`, and `content-engine` read to ground their copy. A guide in a slide deck is invisible to them.
+
+## Auditing for drift
+
+To score a sample against the guide, run three passes:
+
+1. **Ban scan** — does the sample use any banned word? Each hit is a drift point.
+2. **Rule check** — passive voice, sentences over the ceiling, exclamation marks, undefined jargon. Count violations.
+3. **Trait test** — read it cold: which traits surface? If "plain-spoken + confident" reads as "hypey + vague," it is off-brand regardless of word count.
+
+Off-brand reads like everyone else: abstract nouns, hedged claims, AI tells, energy faked with punctuation instead of verbs. The fix is always a rewrite toward a rule, never "make it pop."
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+|---|---|---|
+| Traits = "innovative, passionate, customer-focused" | No competitor claims the opposite; excludes nothing | Pick traits a rival would reject; add this-means/this-does-not-mean |
+| "Be professional" as the only guidance | An LLM and a junior writer can't reproduce an adjective | Quantify into rules (person, length, voice, jargon) + a Bad→Good |
+| Tone "somewhere in the middle" on every axis | Vague middle = no decision = generic output | Commit to a ratio (80/20) and justify it from a trait |
+| Voice changes per channel | Channel-by-channel voices = no recognizable brand | Voice fixed; tone flexes per context (Step 5) |
+| No ban list | Drift and AI tells creep in unchecked | The ban list is the drift killer — ship it first |
+| Guide lives in a deck or someone's head | Downstream skills and LLMs can't read it | Persist machine-readable under `docs/wiki/brand/` |
+| Writing the actual landing/email/article | That is a finished piece, not the definition | Stop; hand to `landing-copy` / `marketing` / `content-engine` |
+
+## Verify
+
+`scripts/verify.sh <guide.md>` is a read-only structural linter for a produced voice guide: it checks the required sections are present (traits, rules with Bad→Good, four-dimension ratios, a non-empty ban list, context matrix, voice-DNA block), flags a trait count outside 3–5, warns on brand-neutral filler used as a trait, and greps the guide's own prose for words it lists in its own ban list (self-consistency). Empty or clean input exits 0 — no false failure.

package/skills/brand-voice/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — brand-voice
+
+`cases.yaml` is read by the catalog harness or run by hand; there is no bundled runner here. `should_trigger` asserts that the SKILL.md description plus body would cause this skill to load for prompts about *defining* how a brand sounds (including a no-keyword drift symptom and a Spanish phrasing). `should_not_trigger` asserts that each near-miss — finished page copy, the brand's visual look, a launch email, a live support reply — routes to the named real sibling (`landing-copy`, `brand-identity`, `marketing`, `customer-support`) instead. The single `capability` case is a rubric-scored generation: have the skill produce a full voice guide for the named brand and check the output against the `must_include` list by reading it — it is a quality judgment, not an automated pass/fail. The structural shape of a produced guide can additionally be checked with `../scripts/verify.sh <guide.md>`.

package/skills/brand-voice/evals/cases.yaml

@@ -0,0 +1,57 @@
+skill: brand-voice
+
+# Prompts that MUST load `brand-voice`. The skill owns the reusable DEFINITION of
+# how a brand sounds: 3-5 traits -> linguistic rules -> four-dimension ratios ->
+# use/avoid word bank -> tone-by-context matrix -> AI voice-DNA block. It never
+# writes the finished landing copy, email, article, or logo.
+should_trigger:
+  - prompt: "We don't have a brand voice guide — help me define our tone of voice."
+    why: "Defining a voice/tone system from scratch is the skill's core artifact job."
+
+  - prompt: "Our blog, our emails, and our support replies all sound like different people wrote them. Fix it."
+    why: "Non-obvious drift symptom with no keyword — the cure is a single shared voice definition, which is exactly what this skill produces."
+
+  - prompt: "Turn these adjectives — 'bold, warm, expert' — into rules a writer can actually follow."
+    why: "Translating fuzzy adjectives into applicable linguistic rules (Step 2) is a named use; the prompt never says 'voice guide'."
+
+  - prompt: "Necesito definir el tono de voz de nuestra marca y una lista de palabras a evitar."
+    why: "Spanish for 'define our brand tone of voice and a list of words to avoid' — traits/tone plus the ban list, both owned here."
+
+  - prompt: "Give me a voice block I can paste into ChatGPT so it always writes like our brand."
+    why: "The AI voice-DNA block (Step 6) — quantified rules + lexicon so an LLM stays on-brand — is the explicit deliverable, not the generated copy itself."
+
+  - prompt: "Audit our last ten emails for off-brand drift against our voice guide and tell me what's wrong."
+    why: "Auditing existing copy for drift against a defined voice is a listed use; it scores against the guide, it does not rewrite the emails."
+
+# NEAR-MISS prompts that must NOT load `brand-voice`. Each routes to the sibling
+# that actually owns it. The trap: anything that produces a FINISHED piece against
+# the voice (copy/email/article), the brand's LOOK (identity), or a live reply.
+should_not_trigger:
+  - prompt: "Write the hero and CTA for our new pricing page."
+    route_to: "landing-copy"
+    why: "Producing finished page copy (hero, value prop, CTA) is landing-copy's job; brand-voice only defines how it should sound."
+
+  - prompt: "Design our logo and pick our brand colors and fonts."
+    route_to: "brand-identity"
+    why: "Logo, color, and typography are the brand's visual identity, owned by brand-identity — how it looks, not how it sounds."
+
+  - prompt: "Write our product launch announcement email."
+    route_to: "marketing"
+    why: "A finished launch email is a marketing deliverable; it reads the voice guide but is not authored here."
+
+  - prompt: "Reply to this angry customer ticket in our usual tone."
+    route_to: "customer-support"
+    why: "Applying the voice to a live ticket is customer-support; it consumes the guide rather than authoring it."
+
+# Rubric-scored generation, not an automated pass/fail.
+capability:
+  - scenario: "Define a complete brand voice guide for a B2B fintech that wants to feel trustworthy but human."
+    must_include:
+      - "3-5 traits, each with a this-means / this-does-not-mean line (reject brand-neutral filler like 'innovative')"
+      - ">=2 linguistic rules per trait, each cluster with a Bad->Good rewrite"
+      - "the four NN/G dimensions (Formal-Casual, Serious-Funny, Respectful-Irreverent, Matter-of-fact-Enthusiastic) positioned as ratios, with a one-line reason each"
+      - "15-20 power words plus an explicit, non-empty ban list including AI tells"
+      - "a tone-by-context matrix covering >=4 contexts, with voice held constant and tone shifting per row"
+      - "a paste-ready AI voice-DNA block (traits + rules + ratios + lexicon)"
+      - "a note to persist the guide under docs/wiki/brand/ so marketing/landing-copy/content-engine can ground against it"
+      - "does NOT write any finished landing copy, email, or article"

package/skills/brand-voice/references/voice-guide-template.md

@@ -0,0 +1,164 @@
+# Voice Guide Template
+
+Fill every slot. Delete the instruction lines in italics before you ship. The finished file lives at `docs/wiki/brand/voice-guide.md`. A fully worked mini-example follows the blank template — copy its shape, not its content.
+
+The persisted guide is an OKF v0.1 wiki article: it MUST open with YAML frontmatter carrying a non-empty `type`. Copy the block below verbatim to the top of `docs/wiki/brand/voice-guide.md`, fill the values, and set `timestamp` to the ISO 8601 datetime of the edit:
+
+```yaml
+---
+type: brand-voice
+title: <brand> — Voice & Tone Guide
+description: How the <brand> brand sounds — traits, rules, dimensions, word bank, and AI voice-DNA.
+tags: [brand-voice, tone-of-voice, voice-guide]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+```
+
+---
+
+## Blank template
+
+### 1. Traits (3–5)
+
+*One adjective per trait. Reject any a competitor would never deny ("innovative", "passionate"). Each gets this-means / this-does-not-mean so it is testable.*
+
+```text
+<Trait 1>
+  this means:         <concrete behavior, e.g. "active voice, short words">
+  this does NOT mean: <the failure mode, e.g. "curt or dumbed-down">
+<Trait 2>
+  this means:         ...
+  this does NOT mean: ...
+<Trait 3>
+  this means:         ...
+  this does NOT mean: ...
+```
+
+### 2. Rules (per trait, 2–3, with a Bad→Good)
+
+*Levers: person · sentence-length ceiling · active/passive · contractions · jargon policy.*
+
+```text
+Trait: <Trait 1>
+  R1  <rule>
+  R2  <rule>
+  Bad : "<off-brand line>"
+  Good: "<on-brand rewrite>"
+```
+
+### 3. Four dimensions (ratios)
+
+| Dimension | Position (ratio) | Why |
+|---|---|---|
+| Formal ↔ Casual | __ / __ | |
+| Serious ↔ Funny | __ / __ | |
+| Respectful ↔ Irreverent | __ / __ | |
+| Matter-of-fact ↔ Enthusiastic | __ / __ | |
+
+### 4. Word bank
+
+- **Power words (15–20):** `...`
+- **Ban list:** `...` *(start from `references/word-bank.md`, then add brand-specific bans)*
+
+### 5. Tone-by-context matrix
+
+| Context | Voice (constant) | Tone shift | Example line |
+|---|---|---|---|
+| Onboarding | | | |
+| Error / failure | | | |
+| Success | | | |
+| Billing / account | | | |
+| Legal / security | | | |
+
+### 6. AI voice-DNA block
+
+```text
+VOICE DNA — <brand>
+Traits: ...
+Rules: ...
+Dimensions: ...
+Use: ...
+Never use: ...
+Tone by context: ...
+```
+
+---
+
+## Worked mini-example — "Larch" (a B2B fintech that wants to feel trustworthy but human)
+
+### 1. Traits
+
+```text
+Trustworthy
+  this means:         we cite the source and the date; we name what we don't know
+  this does NOT mean: stiff, legalistic, or hiding behind disclaimers
+Plain-spoken
+  this means:         short Anglo-Saxon words; one idea per sentence
+  this does NOT mean: oversimplifying the math behind a number
+Human
+  this means:         we write to one person, with contractions, no corporate "we value"
+  this does NOT mean: jokey or casual about someone's money
+```
+
+### 2. Rules
+
+```text
+Trait: Trustworthy
+  R1  Every number carries a source and a date inline.
+  R2  Never hedge with "may", "could", "potentially" to dodge a claim — state it or cut it.
+  Bad : "Returns could potentially be optimized via our solution."
+  Good: "Customers cut reconciliation time 40% in 2025 (internal, n=120)."
+
+Trait: Plain-spoken
+  R1  Sentence ceiling ~20 words.
+  R2  Active voice; the subject acts.
+  Bad : "It is recommended that reconciliation be performed monthly."
+  Good: "Reconcile your accounts every month."
+
+Trait: Human
+  R1  Second person ("you"), contractions ("you'll", "we've").
+  R2  No exclamation marks; warmth comes from clarity, not punctuation.
+  Bad : "We're thrilled to help you on your financial journey!!"
+  Good: "Here's how to close your books faster this month."
+```
+
+### 3. Four dimensions
+
+| Dimension | Position (ratio) | Why |
+|---|---|---|
+| Formal ↔ Casual | 60 / 40 casual | Money topic needs credibility; contractions keep it human. |
+| Serious ↔ Funny | 90 / 10 serious | We handle people's finances; jokes only in onboarding microcopy. |
+| Respectful ↔ Irreverent | 75 / 25 respectful | We challenge legacy-bank jargon, never the reader. |
+| Matter-of-fact ↔ Enthusiastic | 70 / 30 matter-of-fact | Proof over hype; a sourced number beats an adjective. |
+
+### 4. Word bank
+
+- **Power words:** reconcile, close, ledger, clear, accurate, sourced, on time, secure, audit-ready, simple, fast, real, fix, done, plain, trusted.
+- **Ban list:** leverage, seamless, elevate, delve, robust, unlock, game-changer, revolutionize, synergy, best-in-class, "in today's fast-paced world", "financial journey", "thrilled".
+
+### 5. Tone-by-context matrix
+
+| Context | Voice (constant) | Tone shift | Example line |
+|---|---|---|---|
+| Onboarding | trustworthy, plain, human | warm, light | "You're set up. Let's import your first month." |
+| Error / failure | trustworthy, plain, human | plain, reassuring, no humor | "That sync failed. No data was lost — retry below." |
+| Success | trustworthy, plain, human | quiet warmth | "Books closed. Everything reconciled." |
+| Billing / account | trustworthy, plain, human | precise, calm | "Your plan renews June 30. Cancel anytime, no fee." |
+| Legal / security | trustworthy, plain, human | formal, exact | "Funds are held in segregated accounts. See our terms." |
+
+### 6. AI voice-DNA block
+
+```text
+VOICE DNA — Larch
+Traits: trustworthy, plain-spoken, human.
+Rules: active voice; sentences <=20 words; contractions; second person "you";
+  no exclamation marks; every number gets a source + date; no hedging to dodge.
+Dimensions: 60/40 casual, 90/10 serious, 75/25 respectful, 70/30 matter-of-fact.
+Use: reconcile, close, ledger, clear, accurate, sourced, secure, simple, fast, done.
+Never use: leverage, seamless, elevate, delve, robust, unlock, game-changer,
+  revolutionize, synergy, best-in-class, "financial journey", "thrilled".
+Tone by context: onboarding=warm+light; error=plain+reassuring,no humor;
+  success=quiet warmth; billing=precise+calm; legal=formal+exact.
+```

package/skills/brand-voice/references/word-bank.md

@@ -0,0 +1,61 @@
+# Word Bank — Ban List & Power-Word Method
+
+Two jobs: a universal ban list you can adopt as-is, and a method to derive *brand-specific* power words from the traits. The ban list is the drift killer; the power words are what make copy sound like *this* brand and not a competitor. (Oxford College of Marketing, "AI Brand Voice Guidelines," 2025-08-04.)
+
+## Universal ban list (corporate filler + AI tells)
+
+Adopt all of these by default, then add brand-specific bans. These words signal either generic marketing-speak or machine-generated copy:
+
+```text
+leverage              # say "use"
+seamless / seamlessly # say "with no setup" or describe what actually happens
+elevate               # say "improve" or name the concrete gain
+delve                 # say "look at" / "dig into"
+robust                # say what it does (handles X, survives Y)
+unlock                # say "get" / "start"
+game-changer          # show the change, don't label it
+revolutionize         # over-claim; state the measurable difference
+synergy / synergize   # name the actual benefit
+best-in-class         # prove it with a number or drop it
+cutting-edge          # show the capability, not the cliche
+world-class           # same — prove or cut
+in today's fast-paced world   # opening filler; start with the point
+at the end of the day         # filler
+it's important to note         # AI tell; just note it
+embark on a journey            # AI tell
+```
+
+### Why these specifically
+
+Two failure modes converge here. **Corporate filler** ("leverage", "synergy", "best-in-class") says nothing and could describe any company. **AI tells** ("delve", "in today's fast-paced world", "embark on a journey", "it's important to note") are the statistically over-produced phrases of generic LLM output — readers now register them as "a bot wrote this." Banning both is what keeps generated copy on-brand.
+
+## Brand-specific bans
+
+Add words to ban that are correct English but wrong for *this* brand. Examples:
+
+```text
+"users"        -> if the brand says "teams" or "people", ban "users"
+"solution"     -> if the brand names the actual product category, ban "solution"
+"!"            -> if the voice is calm/serious, ban exclamation marks outright
+"thrilled"     -> ban manufactured excitement words for a serious brand
+```
+
+Rule of thumb: if a banned word appears in the brand's own guide prose, the guide contradicts itself. `scripts/verify.sh` catches exactly this.
+
+## Deriving power words from traits
+
+Power words are not a thesaurus dump. Derive 15–20 directly from the traits so the bank is defensible:
+
+1. **List each trait.** e.g. plain-spoken, confident, technical-but-human.
+2. **For each trait, write the verbs and nouns a person living that trait would reach for.**
+   - plain-spoken → ship, fix, build, clear, plain, real, works, done
+   - confident → know, prove, sourced, accurate, on time
+   - technical-but-human → connect, set up, run, simple, fast
+3. **Cut synonyms and abstractions.** Keep words a reader would recognize as concrete. Drop "facilitate", "enable", "optimize" — they are filler in disguise.
+4. **Cap at ~20.** A bank longer than 20 is unmemorable; writers won't internalize it.
+
+The test: read the power-word list cold. If it could belong to any company in the category, it is too generic — push it back toward the traits until it could only be *this* brand.
+
+## How verify.sh uses this
+
+`scripts/verify.sh` confirms a produced guide actually contains a non-empty ban-list block (hard fail if missing) and then greps the guide's own prose for any term it bans (self-consistency warning). It does not enforce *which* words you ban — that is a brand choice — only that a ban list exists and the guide practices what it preaches.

package/skills/brand-voice/scripts/verify.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural linter for a produced brand voice guide.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over ONE voice-guide file you point it at
+#   (markdown / plain text — e.g. docs/wiki/brand/voice-guide.md):
+#     1. Required sections present -> FAIL each missing:
+#        traits, rules (with a Bad->Good), four-dimension ratios,
+#        a word bank, a non-empty BAN list, a tone-by-context matrix,
+#        an AI voice-DNA block.
+#     2. Trait count outside 3-5 -> warn (heuristic; counts the trait block).
+#     3. Brand-neutral filler used AS a trait ("innovative", "passionate",
+#        "customer-focused", "cutting-edge") -> warn each hit.
+#     4. Self-consistency: the guide's own prose uses a word it lists in its
+#        own ban list -> warn each hit.
+#
+#   Only missing structure (#1, incl. an empty ban list) is a hard failure.
+#   Everything else warns. A clean OR empty/whitespace file exits 0 — never a
+#   false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh docs/wiki/brand/voice-guide.md
+#   ./verify.sh guide.md --strict        # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/missing-content file
+#   1  a hard failure (missing required section / empty ban list) — or any
+#      warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno guide file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'brand-voice verify — %s\n\n' "$FILE"
+
+has() { grep -Eiq "$1" "$FILE" 2>/dev/null; }
+
+# --- 1. required sections (hard) ----------------------------------------------
+if has 'trait'; then ok "traits section present"
+else fail "no traits section found (3-5 personality adjectives)"; fi
+
+if has '(^|[^a-z])rules?([^a-z]|$)|this (does not|doesn.t) mean'; then ok "rules section present"
+else fail "no rules section found (traits translated into linguistic rules)"; fi
+
+# A Bad->Good rewrite somewhere proves the rules are concrete, not abstract.
+if grep -Eiq '^[[:space:]]*bad[[:space:]]*:' "$FILE" && grep -Eiq '^[[:space:]]*good[[:space:]]*:' "$FILE"; then
+  ok "Bad->Good rewrite(s) present"
+else
+  fail "no Bad->Good rewrite found — rules must show a concrete before/after"
+fi
+
+# Four-dimension ratios: a ratio token (NN/NN or NN-NN) near a dimension name.
+if grep -Eiq 'formal|serious|respectful|matter-of-fact|enthusiastic' "$FILE" \
+   && grep -Eq '[0-9]{1,3}[[:space:]]*[/-][[:space:]]*[0-9]{1,3}' "$FILE"; then
+  ok "four-dimension ratios present"
+else
+  fail "no four-dimension ratios found (e.g. 80/20 on Formal<->Casual etc.)"
+fi
+
+if has 'word bank|power word'; then ok "word bank present"
+else fail "no word bank found (power words + ban list)"; fi
+
+if has 'tone[- ]by[- ]context|context.*tone|onboarding'; then ok "tone-by-context matrix present"
+else fail "no tone-by-context matrix found"; fi
+
+if has 'voice[- ]?dna|voice block|paste'; then ok "AI voice-DNA block present"
+else fail "no AI voice-DNA block found"; fi
+
+# --- ban list must exist and be non-empty (hard) ------------------------------
+# A ban list is a line introducing it ("Ban list:", "Never use:") that also
+# carries the actual terms after the colon — comma- and/or backtick-delimited.
+# We isolate everything AFTER the colon on those lines; that is the term list.
+MARK='ban[ -]?list|never use|words? to avoid|words? to ban'
+BAN_TERMS_RAW="$(grep -Ei "($MARK)" "$FILE" 2>/dev/null \
+  | sed -E 's/.*(ban[ -]?list|never use|words? to avoid|words? to ban)[^:]*:?//I' \
+  | tr ',`' '\n\n' || true)"
+# Keep single-word candidate terms (skip multi-word phrases for the word-grep).
+BAN_TERMS="$(printf '%s\n' "$BAN_TERMS_RAW" \
+  | grep -Eo '[A-Za-z][A-Za-z-]{3,}' \
+  | grep -Eiv '^(ban|list|never|use|used|words?|to|avoid|the|incl|including|tell|tells|corporate|filler|drift|killer|say|starter|set)$' \
+  | sort -u || true)"
+if [ -n "$BAN_TERMS" ] || printf '%s' "$BAN_TERMS_RAW" | grep -q '[A-Za-z]'; then
+  ok "ban list present and non-empty"
+else
+  fail "no non-empty ban list found — the ban list is the drift killer"
+fi
+
+# --- 2. trait count 3-5 (warn) ------------------------------------------------
+# Heuristic: count "this means" lines, else count bullet/heading lines in the
+# first traits block. Only warns; never fails.
+TRAIT_N="$(grep -Eic 'this means' "$FILE" 2>/dev/null || true)"
+TRAIT_N="${TRAIT_N:-0}"
+if [ "$TRAIT_N" -gt 0 ]; then
+  if [ "$TRAIT_N" -lt 3 ] || [ "$TRAIT_N" -gt 5 ]; then
+    warn "found ~${TRAIT_N} traits (this-means lines) — aim for 3-5"
+  else
+    ok "trait count ~${TRAIT_N} (within 3-5)"
+  fi
+else
+  warn "could not count traits (no 'this means' lines) — confirm 3-5 traits"
+fi
+
+# --- 3. brand-neutral filler used as a trait (warn) ---------------------------
+FILLER='innovative|passionate|customer-focused|customer focused|cutting-edge|cutting edge|world-class'
+# Look only where a trait would sit: a heading/line that is mostly that word.
+F_HITS="$(grep -Eio "($FILLER)" "$FILE" 2>/dev/null | sort -u || true)"
+if [ -n "$F_HITS" ]; then
+  while IFS= read -r h; do
+    [ -n "$h" ] && warn "brand-neutral filler present: \"$h\" — a rival never claims the opposite; pick a trait that excludes someone"
+  done <<EOF
+$F_HITS
+EOF
+else
+  ok "no brand-neutral filler adjectives detected"
+fi
+
+# --- 4. self-consistency: prose uses its own banned words (warn) --------------
+# Re-use the single-word ban terms parsed above. Grep the rest of the file
+# (everything that is NOT a ban-list line) for each as a whole word.
+SELF_HIT=0
+if [ -n "$BAN_TERMS" ]; then
+  # Prose = the file minus the ban-list lines themselves.
+  PROSE="$(grep -Eiv "($MARK)" "$FILE" 2>/dev/null || true)"
+  while IFS= read -r term; do
+    [ -z "$term" ] && continue
+    if printf '%s' "$PROSE" | grep -Eiqw "$term"; then
+      warn "guide prose uses its own banned word: \"$term\" — practice what the guide preaches"
+      SELF_HIT=$((SELF_HIT + 1))
+    fi
+  done <<EOF
+$BAN_TERMS
+EOF
+fi
+[ "$SELF_HIT" -eq 0 ] && ok "no self-contradiction (prose avoids its own ban list)"
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0