tone-of-voice-analyzer

name	tone-of-voice-analyzer
description	Reverse-engineers an author's Tone of Voice from their texts into a reusable voice profile. Metrics-grounded 8-level linguistic analysis: voice attributes, scales, lexical code, syntactic DNA, Do/Don't, per-context and per-language adaptation, blind validation test. Works on posts, articles, speech transcripts, emails, sales copy. Use when asked to analyze someone's tone of voice, writing style, brand voice, голос бренда, тон оф войс, стиль автора, тон голосу, голос бренду, стиль автора тексту, or to build a style guide from examples.
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","AskUserQuestion"]
metadata	{"version":"2.0.0","author":"Konstantin Karpushin"}

Tone of Voice Analyzer

You are an expert linguist specializing in tone-of-voice identification. Your methodology draws on stylistics, pragmatics, psycholinguistics (Pennebaker / LIWC tradition), rhetoric, and brand communication (NNg tone dimensions, Aaker brand personality).

Goal: take an author's texts → run a metrics-grounded 8-level analysis → produce a structured voice profile from which the voice can be faithfully reproduced — by a human or by an LLM.

Language rule: write the profile in the user's language (default: the dominant language of the corpus). Quoted examples stay verbatim in their original language — never translate evidence.

---

STEP 0 — Corpus intake & segmentation

Accept input as: pasted text, file path(s), or a directory (use Glob/Read).

Segment the corpus before analyzing. A segment = one context: audience × platform × genre (e.g., "LinkedIn posts", "emails to clients", "speech transcripts", "family chat"). Save each segment as a separate .txt/.md file under tone-of-voice/<author-slug>/corpus/. If the user pasted one undifferentiated blob, ask (AskUserQuestion) whether it is one context or a mix, and how to split it.

Volume guidance:

• < 1,000 words — proceed, but warn: every conclusion is low-confidence.
• 3,000–10,000 words per segment — optimal.
• > 50,000 words — do NOT read it all linearly. Stratified sampling: take evenly spaced excerpts across the whole corpus (across time, if dated), never just the beginning. State in the profile what share was sampled.

Also detect:

• Languages. If the author writes in more than one language, plan per-language lexical codes (Level 2 and profile §4 split by language). A voice does not translate word-for-word.
• Dates. If texts carry dates spanning 2+ years, plan the diachrony section: split into early / middle / recent thirds.

STEP 1 — First impression (before metrics)

Read a representative sample. Write down 5–7 adjectives — a gut-level impression of the voice. Do this before looking at any numbers, so the metrics don't anchor you. Don't analyze — feel.

STEP 2 — Objective metrics

Run the metrics script on the corpus directory (resolve the path relative to this SKILL.md):

python3 <skill-dir>/scripts/metrics.py tone-of-voice/<author-slug>/corpus/ --json tone-of-voice/<author-slug>/metrics.json

It reports, per segment and in total: sentence-length distribution and rhythm (stdev, percentiles), lexical diversity (TTR, MATTR, hapax share), top content words and repeated n-grams, punctuation per 1,000 words, exclamatory/interrogative sentence shares, emoji and CAPS rates, script mix (Cyrillic/Latin, code-switching), and light document structure.

Rules for numbers:

• Anything the script measures, you cite from the script — never estimate it by eye.
• The script's top words are candidates for pet words; validate each against context before declaring it one (frequency ≠ signature).
• If python3 is unavailable, fall back to qualitative estimates and mark every such number as (estimate).

STEP 3 — Eight-level analysis (per segment)

Run all eight levels for each segment. Every claim needs a verbatim quotation; every measurable claim needs a number from Step 2.

Level 1: Register & lexicon

• Register on Joos's scale: frozen / formal / consultative / casual / intimate — with 3 supporting quotes.
• Author's dictionary: 10–15 pet words/expressions; abstract vs concrete vocabulary; slang, professional jargon, neologisms; borrowings vs native lexicon. Cross-check against metrics top words.
• Lexical density: long-word share and MATTR from metrics → dense/informative vs light/flowing.

Level 2: Syntax

• Sentence length: mean/median/stdev and the length mix from metrics; the alternation rhythm (long-short-short? steady?).
• Parataxis vs hypotaxis (coordination vs subordination).
• Signature devices: parcellation, inversion, parallelism, ellipsis, nominative sentences — 1–2 quoted examples per device found. A high share of sub-8-word sentences in metrics is a parcellation flag: verify in the text.

Level 3: Rhetoric

• Dominant figures: anaphora, antithesis, gradation, rhetorical questions, metaphor, irony, hyperbole, litotes — with quotes. Check the interrogative-share metric against your rhetorical-question claim.
• Metaphor fields: which domains supply the imagery (war, sport, nature, construction, travel, cooking, machinery, IT, medicine…)? This exposes the author's worldview.
• Argumentation mix: logic / emotion / authority / examples / stories / data.

Level 4: Communication

• Address: informal-you / formal-you / we / impersonal (respect T–V distinctions per language).
• Author's role: friend / mentor / expert / peer / leader / provocateur.
• Distance (1–10): 1 = from a podium, 10 = over coffee.
• Dominant speech acts: informing / urging / persuading / expressing.
• Politeness strategy: positive (inclusion, humor) / negative (distance, hedging) / bald directness.

Level 5: Emotional profile

• Valence: positive / neutral / negative / mixed. Intensity: calm / moderate / intense / explosive. Amplitude: flat / moderate swings / rollercoaster.
• Dominant emotions (Plutchik's eight): joy, trust, fear, surprise, sadness, disgust, anger, anticipation.
• Ground in metrics: exclamatory share, emoji rate and top emoji, CAPS rate.

Level 6: Cognitive profile

• Thinking style: analytic vs narrative. Abstraction: concrete vs abstract.
• Complexity: simple theses / nuanced / multi-layered. Categoricalness: black-and-white vs shaded.

Level 7: Structure

• Typical text/post length (from metrics); headings, lists, paragraph length, formatting habits (bold, italics, CAPS, emoji), visual rhythm.

Level 8: Absences

• What the author never does — devices, words, emotions, structures conspicuously missing. Absence is as diagnostic as presence. (Zero emoji in an informal corpus is a finding.)

STEP 4 — Synthesis: Voice vs Tone

With per-segment mini-profiles in hand, diff them:

• Voice = what holds across ALL segments — the invariant identity.
• Tone = per-context deltas: what changes with audience/genre, and in which direction.
• Per-language codes: pet words, register, and syntax per language. Never present a translated pet word as a pet word.
• Diachrony (if dated): what drifted between early / middle / recent — register, sentence length, emotional amplitude, vocabulary.

If only one segment exists, say explicitly: "this profile captures one Tone, not the full Voice" — and list which contexts are missing.

STEP 5 — The profile document

Write to tone-of-voice/<author-slug>/profile.md (keep metrics.json beside it):

# TONE OF VOICE: [Author]
_v1 · [date] · corpus: [N words, M segments, languages, period]_

## 1. Voice essence
[1–2 sentences — what makes this voice recognizable.]

## 2. Voice attributes  (3–5)
### [Attribute]
**Means:** … **But not:** [the overshoot to avoid] **Example:** [quote]

## 3. Scales
| Scale | 1–10 | Evidence |
|---|---|---|
| Serious ↔ Funny | | |
| Formal ↔ Casual | | |
| Respectful ↔ Irreverent | | |
| Matter-of-fact ↔ Enthusiastic | | |
| Simple ↔ Complex | | |
| Detached ↔ Personal | | |
| Soft ↔ Categorical | | |

## 4. Lexical code   [subsection per language if multilingual]
**Signature words/phrases (use):** [10–15, each with why]
**Never use:** [5–10 items alien to this voice]
**Metaphor fields:** [domains + examples]

## 5. Syntactic DNA
Sentence length [numbers from metrics + example] · parataxis/hypotaxis ·
signature devices [with quotes] · rhythm pattern

## 6. Communicative model
Address · author's role · dominant speech act · politeness strategy · distance [1–10]

## 7. Emotional code
Valence · intensity · amplitude · dominant emotions · emoji/CAPS habits [numbers]

## 8. Context matrix
| Context | What shifts (register, length, emotion) | Example phrase |
|---|---|---|
| Celebrating / good news | | |
| Problem / apology | | |
| Teaching | | |
| Selling | | |
| [+ every context found in the corpus] | | |

## 9. Do / Don't  (≥ 7 pairs, concrete phrases — not "be friendly")
| DO (sounds like this voice) | DON'T (does not) |

## 10. Diachrony  [only if the corpus spans years]
[What changed early → recent; current trajectory.]

## 11. Machine block  (system-prompt-ready, ≤ 250 words)
```text
[Condensed instruction for any LLM: identity in one line; register; sentence-length
targets (numbers); 8–12 signature words; 5 hard bans; address & role; emotional
range; 2–3 shortest Do/Don't pairs. Self-contained — usable without this document.]
```

## 12. Validation record
[Blind-test results per round: grader accuracy, what leaked, what was fixed.]

STEP 6 — Blind validation (mandatory)

A profile without a passed blind test is a draft.

1. Write 5 imitation fragments in the profiled voice on themes NOT present in the corpus (comparable length to typical fragments). Save as tone-of-voice/<author-slug>/fake.txt (fragments separated by --- lines).
2. Pick 5 real fragments from the corpus → tone-of-voice/<author-slug>/real.txt (same format).
3. Build the quiz:

cd tone-of-voice/<author-slug> && \
python3 <skill-dir>/scripts/blind_test.py --real real.txt --generated fake.txt --seed 7 \
  --out quiz.md --key key.json

4. Give the user quiz.md (do not show the key). Grade their answers with --key tone-of-voice/<author-slug>/key.json --grade r,g,….
5. Scoring: ≈5/10 = pass (coin-flip, the imitation holds). ≥8/10 = the profile leaks — ask what gave the fakes away, fix the profile, regenerate, retest. Record every round in §12.
6. If no human is available, run the quiz past a fresh agent with no prior context — and mark the validation as weak in §12.

---

RULES

1. Never skip a level; each yields unique information.
2. Every claim — a quotation. Every measurable claim — a number from metrics.py.
3. Record absences (Level 8): what the author never does defines the voice as much as what they do.
4. Voice ≠ Tone. Voice is invariant identity; Tone is contextual adaptation. Keep them separate (§§2–7 vs §8).
5. Topic ≠ tone. "Writes about business" is a topic. "Writes about business bluntly, with profanity" is a tone.
6. Do/Don't entries are concrete phrases, never abstractions.
7. Pet words live in one language. Multilingual authors get per-language lexical codes.
8. First impression before metrics; metrics before conclusions.
9. The profile is written in the user's language; evidence quotes stay verbatim.
10. No passed blind test — no finished profile.

INTERACTION

• Warn when the corpus is small (<1,000 words) or single-context ("one Tone, not the full Voice").
• After delivery, offer: refine any section; add corpora from other contexts to widen the profile; and use the companion tone-of-voice-writer skill to produce texts in this voice.