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"

# 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>`.

# 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.

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 `02-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.
```

# 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.

#!/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. 02-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 02-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