rsc-universal 0.1.1

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+#
+# verify.sh — brand-token gate for the `brand-identity` skill.
+#
+# WHAT IT DOES (read-only; never writes or mutates anything)
+#   Given a W3C design-tokens.json path, validates the brand book's
+#   machine-readable artifact:
+#     1. File exists and parses as JSON (fail loud otherwise).
+#     2. Required color roles present: primary, neutral, accent (anywhere in
+#        the color tree).
+#     3. Every color token carries a HEX value (in its `$value.hex`).
+#     4. For each documented text/background pair under
+#        $extensions["com.risco.contrast"], computes the WCAG 2 relative-
+#        luminance contrast ratio and FAILS any normal-text pair < 4.5:1.
+#        Pairs flagged "logo": true are exempt (WCAG 1.4.3 logo exemption).
+#     5. Prints an ok/skip/warn/fail summary naming the failing pairs.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh path/to/design-tokens.json
+#   ./verify.sh                  # no arg: auto-discovers design-tokens.json,
+#                                #   clean exit 0 if none found (no false fail)
+#   ./verify.sh --help
+#
+# EXIT CODES
+#   0  no failures (also: empty/clean target — nothing to check)
+#   1  a real failure (bad JSON, missing role, color w/o hex, AA pair < 4.5:1)
+#   2  bad usage
+#
+# Dependency-light: prefers python3 (stdlib only) for JSON + contrast math.
+# If python3 is absent, JSON-dependent checks are SKIPPED, never failed.
+
+set -euo pipefail
+
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+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,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# --- arg parse --------------------------------------------------------------
+TOKENS=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *) TOKENS="$1"; shift ;;
+  esac
+done
+
+# --- locate the tokens file (clean exit if none — no false failure) ---------
+if [ -z "$TOKENS" ]; then
+  # search common spots; pick the first match. Never fail when absent.
+  for cand in \
+    ./design-tokens.json \
+    ./tokens/design-tokens.json \
+    ./02-DOCS/wiki/brand/design-tokens.json; do
+    if [ -f "$cand" ]; then TOKENS="$cand"; break; fi
+  done
+  if [ -z "$TOKENS" ]; then
+    found="$(find . -maxdepth 4 -name 'design-tokens.json' -type f 2>/dev/null | head -n1 || true)"
+    [ -n "$found" ] && TOKENS="$found"
+  fi
+fi
+
+if [ -z "$TOKENS" ]; then
+  skip "no design-tokens.json found — nothing to verify (pass a path to check one)"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+if [ ! -f "$TOKENS" ]; then
+  fail "tokens file not found: $TOKENS"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 1
+fi
+
+# --- the JSON + contrast checks (python3 stdlib) ----------------------------
+if ! have python3; then
+  skip "python3 not found — JSON/contrast checks skipped (install python3 to enable)"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# python prints lines prefixed OK:/FAIL:/WARN:/SKIP: which we route to the
+# bash counters so the summary + exit code stay in one place.
+REPORT="$(python3 - "$TOKENS" <<'PY'
+import json, sys
+
+path = sys.argv[1]
+out = []
+
+try:
+    with open(path, encoding="utf-8") as fh:
+        data = json.load(fh)
+except json.JSONDecodeError as e:
+    print(f"FAIL:tokens file does not parse as JSON: {e}")
+    sys.exit(0)
+except OSError as e:
+    print(f"FAIL:cannot read tokens file: {e}")
+    sys.exit(0)
+
+print("OK:tokens file parses as JSON")
+
+# --- walk: collect every color token (node with $type==color or $value w/ hex)
+colors = []          # (dotted_path, hex_or_None)
+role_names = set()   # leaf + group key names seen, lowercased
+
+def walk(node, trail, inherited_type=None):
+    if not isinstance(node, dict):
+        return
+    ntype = node.get("$type", inherited_type)
+    if "$value" in node:
+        if ntype == "color" or isinstance(node["$value"], dict):
+            val = node["$value"]
+            hexv = val.get("hex") if isinstance(val, dict) else None
+            if isinstance(val, str) and val.startswith("#"):
+                hexv = val
+            if ntype == "color" or (isinstance(val, dict) and "colorSpace" in val):
+                colors.append((".".join(trail), hexv))
+        return
+    for k, v in node.items():
+        if k.startswith("$"):
+            continue
+        role_names.add(k.lower())
+        walk(v, trail + [k], ntype)
+
+walk(data.get("color", {}), ["color"], None)
+
+# --- required roles present
+for role in ("primary", "neutral", "accent"):
+    if role in role_names:
+        print(f"OK:required color role present: {role}")
+    else:
+        print(f"FAIL:required color role missing: {role}")
+
+# --- every color token carries a hex
+if not colors:
+    print("WARN:no color tokens found under 'color'")
+else:
+    missing = [p for p, h in colors if not h]
+    if missing:
+        for p in missing:
+            print(f"FAIL:color token has no hex value: {p}")
+    else:
+        print(f"OK:all {len(colors)} color tokens carry a hex value")
+
+# --- WCAG 2 contrast on documented pairs
+def lin(c):
+    c = c / 255.0
+    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+def luminance(hexstr):
+    h = hexstr.lstrip("#")
+    if len(h) == 3:
+        h = "".join(ch * 2 for ch in h)
+    if len(h) != 6:
+        return None
+    try:
+        r, g, b = (int(h[i:i+2], 16) for i in (0, 2, 4))
+    except ValueError:
+        return None
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+
+def ratio(fg, bg):
+    lf, lb = luminance(fg), luminance(bg)
+    if lf is None or lb is None:
+        return None
+    hi, lo = max(lf, lb), min(lf, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+pairs = (data.get("$extensions", {}) or {}).get("com.risco.contrast", [])
+if not pairs:
+    print("SKIP:no documented text/background pairs ($extensions.com.risco.contrast) — contrast not checked")
+else:
+    for p in pairs:
+        fg, bg = p.get("fg"), p.get("bg")
+        use = p.get("use", "text")
+        is_logo = bool(p.get("logo"))
+        r = ratio(fg, bg) if fg and bg else None
+        if r is None:
+            print(f"WARN:could not compute contrast for pair {fg} on {bg} ({use})")
+            continue
+        if is_logo:
+            print(f"SKIP:logo-exempt pair {fg} on {bg} ({use}): {r:.2f}:1 (WCAG 1.4.3 logo exemption)")
+        elif r < 4.5:
+            print(f"FAIL:contrast {r:.2f}:1 < 4.5:1 AA — {fg} on {bg} ({use})")
+        else:
+            print(f"OK:contrast {r:.2f}:1 >= 4.5:1 AA — {fg} on {bg} ({use})")
+PY
+)"
+
+while IFS= read -r line; do
+  [ -z "$line" ] && continue
+  case "$line" in
+    OK:*)   ok   "${line#OK:}" ;;
+    FAIL:*) fail "${line#FAIL:}" ;;
+    WARN:*) warn "${line#WARN:}" ;;
+    SKIP:*) skip "${line#SKIP:}" ;;
+    *)      printf '%s\n' "$line" ;;
+  esac
+done <<EOF
+$REPORT
+EOF
+
+printf '\nverified: %s\n' "$TOKENS"
+printf 'ok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+[ "$fail_count" -gt 0 ] && exit 1
+exit 0

package/skills/brand-voice/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: brand-voice
+description: "Use when defining or documenting how a brand SOUNDS — turning fuzzy adjectives ('professional but approachable') into voice rules a writer or LLM can actually apply, building a use/avoid word bank, plotting tone on the four dimensions, or producing an AI voice-DNA block so generated copy stays on-brand. Also when content drifts: blog, emails, and support replies read like five different people wrote them. Triggers: 'define our tone of voice', 'we have no brand voice guide', 'turn these adjectives into rules', 'word bank / banned words', 'make ChatGPT write like us', 'our content sounds like AI', 'everything sounds off-brand', 'define el tono de voz de la marca', 'la nostra veu de marca'. NOT writing the actual landing copy (that is landing-copy), the launch email (that is marketing), or the logo/colors (that is 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
+
+*The durable definition of how a brand sounds. You write it once; everything downstream writes against it. This skill produces the guide, never the finished piece of copy.*
+
+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, not a landing page, email, or article. Those are downstream consumers that *read* this guide.
+
+## When to use / When NOT
+
+Use when:
+
+- A brand has no voice guide, or has one that is just a list of adjectives nobody can apply.
+- Fuzzy adjectives ("bold, warm, expert") must become rules a writer or LLM can follow.
+- Building the word bank: power words to lean on, words/phrases to ban.
+- Specifying how tone shifts by context (error vs. celebration vs. legal) while voice stays constant.
+- Producing the AI voice-DNA block to paste into a system prompt so generated copy stays on-brand.
+- Auditing existing copy for off-brand drift against a defined voice.
+- The drift symptom: "our blog, emails, and support replies all sound like different people."
+
+Do NOT use when (route to the sibling that owns it):
+
+- Writing the hero / value prop / CTA / section copy of a page → `landing-copy`.
+- Writing launch emails, channel posts, or finished marketing pieces → [`../marketing/SKILL.md`](../marketing/SKILL.md), and for blog/article systems → `content-engine`, `article-writing`, `newsletter`, `social-publisher`.
+- Logo, color, type, visual identity, design tokens → `brand-identity`.
+- Visual/UX layout, motion, component look → [`../design/SKILL.md`](../design/SKILL.md).
+- An investor narrative or sales deck → [`../pitch-deck/SKILL.md`](../pitch-deck/SKILL.md).
+- Replying to a live customer ticket in-tone → `customer-support` (it consumes this guide; it does not author it).
+
+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. The way the brand *looks* is `brand-identity`.
+
+## 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 `02-DOCS/wiki/brand/voice-guide.md` and the voice-DNA block beside it, per the `harness` Karpathy-wiki convention (compiled brand articles under `02-DOCS/wiki/brand/`, raw user inputs under `02-DOCS/raw/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 `02-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` |
+
+## Templates
+
+A fill-in-the-blanks guide (traits → rules → 4-D ratios → word bank → context matrix → voice-DNA block) with one fully worked mini-example brand lives in [`references/voice-guide-template.md`](references/voice-guide-template.md). The universal ban list and power-word derivation method are in [`references/word-bank.md`](references/word-bank.md).
+
+## 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 02-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,150 @@
+# Voice Guide Template
+
+Fill every slot. Delete the instruction lines in italics before you ship. The finished file lives at `02-DOCS/wiki/brand/voice-guide.md`. A fully worked mini-example follows the blank template — copy its shape, not its content.
+
+---
+
+## 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.
+```