voice-sweep

Voice Sweep

A grep-strength brand-voice gate. Scans every text file in the project against a brand-profile JSON and flags banned phrases, stale numeric claims, and missed reframes. Built so when positioning shifts, you can ship the new voice across the codebase in one PR — no LLM, no ambiguity, no missed surfaces.

When to use

Trigger this skill when:

• A user asks to "voice sweep", "find banned phrases", "tone check", "brand voice audit", "find old positioning", "find stale stats"
• After a positioning or pricing change, before declaring the rollout complete
• As a CI gate that prevents regressions to deprecated copy
• When QA flags a tone inconsistency and you need to find every other surface that needs the same edit

Do NOT use for:

• Design-system rule violations (use design-audit skill instead)
• Visual layout / overflow checks (use visual-qa skill instead)
• Spelling / grammar (use a dedicated linter)

How to invoke

npx @operator-skills/voice-sweep

Common flags:

Flag	What it does
--profile <path>	Path to brand-profile JSON (default: ./voice-sweep.profile.json)
--remote-profile <url>	Fetch brand-profile from a URL (opt-in, no LLM)
--glob <pattern>	Override default glob (default: src/**/*.{ts,tsx,jsx,js,md,mdx})
--format table|json	Output format (default: table)
--verbose	Per-finding detail with file:line + excerpt
--severity error|warn|info	Minimum severity to surface

Exit codes: 0 clean, 1 finding at-or-above severity, 2 config error.

Brand profile schema

The brand profile is a plain JSON file. The default location is voice-sweep.profile.json at the repo root. Each rule type has a severity and a list of patterns; patterns can be plain strings (exact substring match, case-insensitive) or { regex: "...", flags: "..." } objects.

{
  "$schema": "https://github.com/cmj-hub/operator-skills/blob/main/skills/voice-sweep/references/profile-schema.json",
  "name": "JMC brand voice — spine reframe (2026)",
  "version": "1.0",
  "rules": {
    "banned-phrases": {
      "severity": "error",
      "patterns": [
        "install our methodology",
        "scorecards + 90-day plans",
        "419+ assets",
        { "regex": "\\b7 Pro (SaaS )?[Tt]ools\\b", "message": "Use \"14 Prototypes\" or current post-cull count" }
      ]
    },
    "stale-stat-claims": {
      "severity": "warn",
      "patterns": [
        { "regex": "\\b\\d{3,}\\+ scorecards\\b", "message": "Numeric scorecard count is deprecated; use 'growing weekly'" }
      ]
    },
    "preferred-reframes": {
      "severity": "info",
      "patterns": [
        { "regex": "\\bbuy the (system|methodology|process)\\b", "message": "Prefer 'seat on the build' framing" }
      ]
    }
  },
  "ignore": ["src/legacy/**", "**/*.test.tsx"]
}

Built-in rule categories

The profile supports any rule category — these are just conventions for organizing patterns. Each category gets its own severity:

• banned-phrases — exact text that must not appear (error by default)
• stale-stat-claims — numeric claims that may have changed (warn)
• preferred-reframes — old phrasings that have a better successor (info)
• Custom categories — name them anything; the report groups by category

Per-file suppressions

{/* @voice-sweep: allow banned-phrases */}
{/* Reason: legacy testimonial quote — verbatim, do not edit */}
<p>"They installed our methodology in two weeks."</p>

The Reason: line must appear within 5 lines after the suppression.

Best-practice usage in CI

- name: Voice sweep
  run: npx @operator-skills/voice-sweep --severity error

Fails the build on any error-level finding. Run a --severity warn variant on a nightly cadence to catch slower decay.

Cross-runtime

This skill works in:

• Plain Node CLI — npx @operator-skills/voice-sweep
• Claude Code (Agent Skills) — install via /plugin install voice-sweep; Claude auto-invokes when trigger phrases match
• MCP — wire npx @operator-skills/voice-sweep mcp into any MCP-aware runtime
• Cursor / Gemini / Codex — planned Wave 2

Related skills

• design-audit — static-analysis design-system checks
• visual-qa — runtime layout / overflow checks (Playwright)