---
name: kodadocs-brand-voice
description: "Analyze existing content to extract a brand voice style guide, then validate and rewrite documentation to match."
---

# Brand Voice Analyzer

## Overview

This skill analyzes your project's existing content (README, website copy, marketing pages, existing documentation) to extract tone and style characteristics, then produces a project-specific writing style guide. The style guide is used to validate generated documentation articles and rewrite any that do not match the established voice.

Use this skill when:
- You want your auto-generated documentation to match your existing brand tone
- Your README has a distinct voice (casual, technical, playful, corporate) and docs should follow it
- You are generating documentation for the first time and want to define the writing standards
- You have existing articles that feel inconsistent and want to normalize them
- You want a reusable style guide that persists across future documentation runs

## Prerequisites

Before running this skill, ensure the following:

1. **Existing content to analyze:** At least one of these should exist:
   - `README.md` in the project root
   - A marketing website or landing page (provide URL)
   - Existing documentation files (markdown, HTML, or text)
   - A `package.json` with a description field
2. **KodaDocs manifest (optional):** If validating generated articles, a previous pipeline run should exist with articles in the manifest.

## Workflow

### Step 1: Gather Source Content

Collect all available content that represents the project's voice.

**Local files to scan (check each, use what exists):**
```
README.md
CONTRIBUTING.md
docs/**/*.md
src/**/README.md
.github/ISSUE_TEMPLATE/*.md
.github/PULL_REQUEST_TEMPLATE.md
package.json (description field)
pyproject.toml (description field)
Cargo.toml (description field)
```

Use `Glob` to find markdown files:
```
pattern: "**/*.md"
```

Filter out generated files (node_modules, .next, dist, build, vendor).

**Remote content (if URL provided):**
Use `WebFetch` to retrieve landing page or marketing site content. Extract:
- Hero text and tagline
- Feature descriptions
- Any "about" or "how it works" sections
- Call-to-action text
- Footer copy

**Minimum content requirement:** At least 500 words of source material across all collected content. If under 500 words, warn the user that the analysis may be unreliable.

### Step 2: Analyze Tone Characteristics

Process the collected content to identify voice characteristics across multiple dimensions.

**Dimension 1: Formality (1-5 scale)**

| Score | Label | Signals |
|-------|-------|---------|
| 1 | Very casual | Slang, contractions, exclamation marks, humor, emoji |
| 2 | Casual | Contractions, conversational phrasing, "you" and "we" |
| 3 | Neutral | Mix of formal and informal, standard technical writing |
| 4 | Professional | No contractions, measured tone, third-person references |
| 5 | Very formal | Academic style, passive voice, no colloquialisms |

**Dimension 2: Technical Depth (1-5 scale)**

| Score | Label | Signals |
|-------|-------|---------|
| 1 | Non-technical | No jargon, plain language, step-by-step hand-holding |
| 2 | Beginner-friendly | Terms are defined, concepts are explained, analogies used |
| 3 | Intermediate | Assumes some technical background, terms used without definition |
| 4 | Advanced | Dense technical content, assumes domain expertise |
| 5 | Expert-only | Academic or research-level, heavy notation, niche terminology |

**Dimension 3: Personality (descriptive tags)**

Select all that apply from the content analysis:
- Opinionated vs. Neutral
- Encouraging vs. Matter-of-fact
- Playful vs. Serious
- Concise vs. Detailed
- Direct vs. Diplomatic
- Bold vs. Conservative
- Developer-centric vs. Business-centric

**Dimension 4: Sentence Structure**

Measure from the source content:
- Average sentence length (words)
- Average paragraph length (sentences)
- Use of bullet points vs. prose (ratio)
- Use of code examples (frequency: rare, occasional, frequent)
- Use of headings (how many levels deep, how frequently)

**Dimension 5: Vocabulary Patterns**

Identify from the source:
- Commonly used terms (words that appear 3+ times)
- Avoided terms (notably absent words common in similar projects)
- Branded terms (project-specific language, e.g., "pipeline" instead of "workflow")
- Pronouns: "we" vs. "I" vs. "you" vs. passive/impersonal
- Action verbs preference (e.g., "run" vs. "execute", "build" vs. "construct")

### Step 3: Build the Style Guide

Produce a structured style guide document from the analysis.

**Style guide template:**

```markdown
# <Project Name> Documentation Style Guide

## Voice Summary

<2-3 sentence summary of the overall voice, e.g., "KodaDocs documentation is
written in a casual, developer-to-developer tone. It assumes intermediate
technical knowledge and favors concise, direct explanations over lengthy
prose.">

## Tone Profile

- **Formality:** <score>/5 — <label>
- **Technical depth:** <score>/5 — <label>
- **Personality:** <comma-separated tags>
- **Perspective:** <first person / second person / third person / mixed>

## Writing Rules

### Do

- <Rule based on analysis, e.g., "Use contractions (you're, it's, don't)">
- <Rule, e.g., "Address the reader as 'you'">
- <Rule, e.g., "Include a code example in every section">
- <Rule, e.g., "Keep paragraphs to 3 sentences or fewer">
- <Rule, e.g., "Use active voice">

### Don't

- <Rule, e.g., "Don't use passive voice">
- <Rule, e.g., "Don't write paragraphs longer than 4 sentences">
- <Rule, e.g., "Don't use 'simply' or 'just' — they minimize difficulty">
- <Rule, e.g., "Don't use corporate jargon (leverage, utilize, synergy)">

## Vocabulary

### Preferred Terms

| Use | Instead of |
|-----|-----------|
| <preferred> | <avoided> |
| run | execute |
| build | construct |
| set up | configure |

### Branded Terms

- **<term>:** <definition and usage context>

### Banned Words

<list of words/phrases that should never appear in documentation>

## Sentence Structure

- **Target sentence length:** <N> words (range: <min>-<max>)
- **Target paragraph length:** <N> sentences
- **Code examples:** <frequency — every section / every page / where relevant>
- **Bullet points:** <preferred for lists of 3+ items / use sparingly>

## Examples

### Good (matches voice)

> <A 2-3 sentence example paragraph that matches the detected voice>

### Bad (does not match voice)

> <The same content rewritten in the wrong voice, with annotations
> explaining what is wrong>
```

### Step 4: Save the Style Guide

Save the style guide to the project for future use.

**Default location:** `.kodadocs/style-guide.md`

This location is chosen because:
- It lives alongside other KodaDocs configuration
- It persists across pipeline runs
- Future skill runs can read it automatically

Also save a machine-readable version at `.kodadocs/style-guide.json`:
```json
{
  "formality": 2,
  "technical_depth": 3,
  "personality": ["opinionated", "concise", "developer-centric"],
  "perspective": "second-person",
  "avg_sentence_length": 14,
  "avg_paragraph_length": 3,
  "use_contractions": true,
  "use_active_voice": true,
  "code_example_frequency": "frequent",
  "preferred_terms": {"run": "execute", "build": "construct"},
  "banned_words": ["simply", "just", "leverage", "utilize"]
}
```

### Step 5: Validate Existing Articles (Optional)

If articles have been generated from a previous KodaDocs pipeline run, validate them against the style guide.

**Load existing articles:**
Call `mcp__kodadocs__load_manifest` to get the current pipeline state. Extract the articles list from the manifest.

**Validation checklist for each article:**

1. **Formality match:** Does the article's tone match the target formality score (+/- 1)?
2. **Technical depth:** Is the content at the right level for the audience?
3. **Perspective consistency:** Does it use the correct pronouns throughout?
4. **Vocabulary compliance:** Are any banned words used? Are preferred terms used correctly?
5. **Sentence length:** Is the average within the target range?
6. **Paragraph length:** Are paragraphs the right length?
7. **Code examples:** Are they present at the expected frequency?
8. **Active/passive voice:** Does it match the style guide preference?

**Scoring:**
- Each checklist item is pass/fail
- Articles scoring 6/8 or better: PASS (no changes needed)
- Articles scoring 4-5/8: WARN (suggest revisions)
- Articles scoring 3/8 or below: FAIL (rewrite recommended)

**Output a validation report:**
```markdown
# Voice Validation Report

## Summary
- Articles validated: 8
- Passed: 5
- Warnings: 2
- Failed: 1

## Results

### "Getting Started" — PASS (7/8)
- [x] Formality match
- [x] Technical depth
- [x] Perspective
- [x] Vocabulary
- [ ] Sentence length (avg 22 words, target 14)
- [x] Paragraph length
- [x] Code examples
- [x] Active voice

### "Authentication" — FAIL (3/8)
- [ ] Formality match (too formal, score 4 vs target 2)
- [x] Technical depth
- [ ] Perspective (uses "the user" instead of "you")
- [ ] Vocabulary (uses "utilize" 3 times)
- [ ] Sentence length (avg 28 words, target 14)
- [x] Paragraph length
- [x] Code examples
- [ ] Active voice (60% passive)
**Recommendation:** Rewrite this article.
```

### Step 6: Rewrite Non-Conforming Articles (Optional)

For articles that scored WARN or FAIL, offer to rewrite them.

**Rewriting process:**

1. Read the original article content
2. Apply the style guide rules systematically:
   - Replace banned words with preferred alternatives
   - Convert passive voice to active voice where flagged
   - Break long sentences (>target + 5 words) into shorter ones
   - Break long paragraphs (>target + 1 sentence) into shorter ones
   - Adjust formality (add/remove contractions, adjust register)
   - Ensure correct perspective pronouns
   - Add code examples if missing and expected
3. Preserve all factual content -- never change the meaning, only the style
4. Preserve all code blocks unchanged (do not rewrite code)
5. Preserve headings structure unchanged

**After rewriting:**
- Re-run the validation checklist to confirm improvement
- If the rewritten article still does not pass, flag it for manual review
- Save the rewritten articles and update the manifest

### Step 7: Reassemble Doc Site (Optional)

If articles were rewritten:

1. Call `mcp__kodadocs__assemble_vitepress` with the updated articles
2. Preserve all existing site configuration from the manifest
3. Call `mcp__kodadocs__deploy_site` if the user requests redeployment
4. Call `mcp__kodadocs__save_manifest` to record the changes

## Decision Trees

### Source Content Selection

```
Does README.md exist and contain 200+ words?
  YES -> Use as primary voice source
  NO  -> Does a marketing URL exist?
           YES -> Fetch and use as primary voice source
           NO  -> Are there existing docs (docs/**/*.md)?
                    YES -> Use as primary voice source
                    NO  -> Use package.json/pyproject.toml description + any .md files found
                           Warn: "Limited source content. Style guide may be generic."
```

### Validation Scope

```
Does the user want to validate existing articles?
  YES -> Does .kodadocs/run_manifest.json exist?
           YES -> Load articles from manifest and validate
           NO  -> Are there markdown files in docs/ or a docs output directory?
                    YES -> Validate those files
                    NO  -> Nothing to validate. Generate style guide only.
  NO  -> Generate style guide only. Skip Steps 5-7.
```

### Rewrite Decision

```
Did any articles score WARN or FAIL?
  YES -> Ask the user: "N articles don't match the style guide. Rewrite them?"
           User says YES -> Rewrite and reassemble
           User says NO  -> Output the validation report only
  NO  -> All articles match. No rewriting needed.
```

### Conflicting Signals

```
Does the source content have mixed tones (e.g., casual README but formal CONTRIBUTING)?
  YES -> Weight the README and user-facing content higher than contributor docs
         Note the conflict in the style guide: "Note: contributor-facing docs use a
         more formal tone. This guide covers user-facing documentation only."
  NO  -> Proceed normally
```

## Output Format

The skill produces:

1. **Style guide** (`.kodadocs/style-guide.md`) - Human-readable writing guidelines
2. **Style config** (`.kodadocs/style-guide.json`) - Machine-readable style parameters
3. **Validation report** (optional, `.kodadocs/voice-validation.md`) - Per-article conformance results
4. **Rewritten articles** (optional) - Updated articles that match the style guide
5. **Console summary:**

```
Brand voice analysis complete:
  Source content: 3,400 words across 4 files
  Voice profile:
    - Formality: 2/5 (Casual)
    - Technical depth: 3/5 (Intermediate)
    - Personality: opinionated, concise, developer-centric
    - Perspective: second-person ("you")
  Style guide saved to: .kodadocs/style-guide.md
  Style config saved to: .kodadocs/style-guide.json
  Validation: 5 passed, 2 warnings, 1 failed (of 8 articles)
```

## Error Handling

### No source content found
If no README, docs, or marketing URL is available:
- Stop and inform the user: "No existing content found to analyze. Provide a README.md, docs directory, or marketing URL."
- Do not generate a generic style guide without source material

### Insufficient source content
If total source content is under 500 words:
- Proceed with analysis but add a disclaimer to the style guide
- Note: "This style guide was generated from limited source material (<500 words). Review and adjust the rules for accuracy."

### Source content in multiple languages
If content is found in more than one human language:
- Identify the primary language (most content)
- Generate the style guide for the primary language
- Note the secondary languages: "Additional content found in [language]. This guide covers [primary language] only."

### Style guide already exists
If `.kodadocs/style-guide.md` already exists:
- Ask the user: "A style guide already exists. Overwrite it with a fresh analysis, or keep the existing one?"
- If overwrite: back up the old file to `.kodadocs/style-guide.backup.md`
- If keep: use the existing guide for validation only (skip Steps 1-4)

### Validation disagreements
If the validation results seem wrong (e.g., a clearly well-written article fails):
- The style guide thresholds may be too strict
- Suggest the user review and adjust the rules in `.kodadocs/style-guide.json`
- Never auto-rewrite without user confirmation

### WebFetch fails for marketing URL
If the provided marketing URL cannot be fetched:
- Log the warning: "Could not fetch [URL]. Proceeding with local content only."
- Continue with whatever local content is available

## Success Criteria

The run is successful when:
- [ ] At least 500 words of source content were analyzed (or warning was shown)
- [ ] All 5 tone dimensions were scored
- [ ] Style guide includes Do/Don't rules derived from actual content patterns
- [ ] Vocabulary section includes project-specific preferred and banned terms
- [ ] Good/bad examples are included and clearly annotated
- [ ] Style guide saved to `.kodadocs/style-guide.md`
- [ ] Machine-readable config saved to `.kodadocs/style-guide.json`
- [ ] If validation was run: each article has a pass/warn/fail score
- [ ] If rewriting was run: rewritten articles pass the validation checklist
- [ ] Console summary was printed with voice profile statistics
