voice-gate

name	voice-gate
description	Line-editor pass on any content draft against a client voice guide. Flags cadence issues, signature-move overuse, voice-guide violations, receipt gaps — things a rule-based gate can't catch. Use after /content-gate and before human review.

/voice-gate — The Line Editor

Run a subjective-voice review of a drafted piece against a client's voice guide. Produces a structured editorial report with severity-ranked issues, verbatim quotes, rule citations, and direction for human-editor fixes.

This is the complementary pass to /content-gate. Rule-based gates (Four U's, banned words, SEO lint) catch mechanical quality issues. Voice Gate catches what they can't: sing-songy cadence, signature-move overuse, voice-guide violations that require interpretation, receipt gaps, and flow. Claude Code's session executes the judge prompt inline — no external API, no script wrapper, no env vars.

Preamble

source "$(dirname "$0")/../lib/preamble.sh"

Arguments

Required:

• file path: Path to the draft markdown file to review.

Optional:

• --voice-guide : Path to the client's writing guide. If omitted, auto-discovered (see Step 1).
• --persona : Path to the writer persona file for extra biographical context. Optional but improves flag specificity.
• --max-issues : Cap the number of issues in the report. Default 30.

Example: /voice-gate clients/GrowthModeOn/outputs/blog-posts/how-to-write-a-podcast-pitch.md Example: /voice-gate path/to/draft.md --voice-guide path/to/writing-guide.md --persona path/to/persona.md

The Skill

Step 1: Resolve Arguments

Parse ARGUMENTS. The first positional argument is the draft file path. Use the Read tool to validate it exists. If the draft is not a readable markdown file, stop and tell the user: "Draft not found: {path}. Pass a valid markdown file path."

Resolve the voice guide:

• If --voice-guide <path> is provided, use that path.
• Otherwise, auto-discover. Walk up from the draft's directory until you find an outputs/personas/ directory (or a plain personas/ directory). Inside, look for a file matching *-writing-guide.md. The canonical convention is clients/<client>/outputs/personas/<writer>-writing-guide.md. Pick the first match in the closest candidate directory.
• If no match is found, stop and tell the user: "No voice guide found. Pass --voice-guide <path> explicitly, or place a *-writing-guide.md file in the nearest outputs/personas/ directory."

Resolve the persona (optional):

• If --persona <path> is provided, use it.
• Otherwise, look in the same directory as the resolved voice guide for a sibling *-persona.md whose basename prefix matches the writing guide (e.g. lexie-smith-writing-guide.md → lexie-smith-persona.md). If found, use it. If not, proceed without a persona.

Resolve max-issues: default 30. Parse --max-issues <n> if present and coerce to an integer.

Step 2: Read Inputs

Use the Read tool to load:

• The draft file (full text).
• The voice guide (full text).
• The persona file (full text, if resolved).

If any required file fails to read, surface the error and stop.

Step 3: Load the Judge Prompt

Use the Read tool to load voice-gate/judge-prompt.md from this skill's own directory. This is the rubric Claude applies to produce the editorial report. If the file is missing, stop and tell the user: "Voice Gate judge prompt missing at voice-gate/judge-prompt.md. Re-install the skill."

Step 4: Execute the Judge Prompt (inline)

You (Claude) are the judge. There is no external API call. Apply the judge prompt against the three inputs: the draft text, the voice guide text, and (if present) the persona text. Produce a structured editorial report that conforms to the output contract defined in judge-prompt.md.

Hard requirements on the report — these are non-negotiable:

• Every issue cites a verbatim quote from the draft (never a paraphrase).
• Every issue references a specific rule — a numbered section of the voice guide (e.g., "Voice guide §11 DO #4"), a named signature-move cap ("I repeat — cap 1, count 3"), or a named editorial principle when the voice guide is silent ("Editorial: triple-list cadence monotony").
• Severity is one of: High (publish-blocking), Medium (meaningful craft issue), Low (polish).
• Recommended fixes are direction only, never rewrites. The human editor owns the rewrite.
• If the total issue count exceeds max_issues, include only the top max_issues by severity and note in the Summary Table that the cap was hit.

Step 5: Write the Report

Derive the report path: <draft-path-without-extension>.VOICE-GATE.md. Example: .../how-to-write-a-podcast-pitch.md → .../how-to-write-a-podcast-pitch.VOICE-GATE.md.

Use the Write tool to save the report at that path.

Step 6: Compute the Verdict

Count issues by severity. Apply the verdict logic:

• PASS: 0 High issues AND ≤3 Medium issues. Message: "Ready for human review."

• HOLD: 1–2 High issues OR >3 Medium issues (and no FAIL triggers). Message: "Moderate edits needed. See report."

• FAIL: 3+ High issues OR any voice-guide hard-rule violation. Hard-rule violation triggers:

  • A Tier 1 banned word from the voice guide's DON'T list appears in the draft.
  • A year-count canonicalization rule is violated (e.g., the guide canonicalizes "15+ years" but draft says "13 years" or "11 years").
  • An AI-slop phrase the guide explicitly flags appears ("In conclusion," "delve," "innovative," "disruptive," "holistic," etc., per the guide's forbidden list).
  • The cold-open rule for SEO posts is violated (e.g., "Hey guys" opening a blog post).

  Message: "Blocking issues. Fix before human review."

Step 7: Display the Summary

Print a concise scorecard:

VOICE GATE REPORT
═══════════════════════════════════════════
File:        {draft_filename}
Voice guide: {voice_guide_filename}
Persona:     {persona_filename or "—"}
Report:      {report_path}

Issues:      {total} total
  High:      {high}
  Medium:    {medium}
  Low:       {low}

VERDICT: {PASS | HOLD | FAIL}
{verdict_message}

Top 3 issues:
  1. [{severity}] {category} — {one_line_summary}
  2. [{severity}] {category} — {one_line_summary}
  3. [{severity}] {category} — {one_line_summary}

Full report: {report_path}

Step 8: Save the Gate Log

Append a log entry to ~/.kai-marketing/gates/{date}-{slug}-voice.json — where {date} is today's date in YYYY-MM-DD and {slug} is the draft filename stem. One log file per draft per day (overwrite if the file already exists).

{
  "file": "{draft_path}",
  "voice_guide": "{voice_guide_path}",
  "persona": "{persona_path or null}",
  "report_path": "{report_path}",
  "verdict": "{PASS|HOLD|FAIL}",
  "high_count": {n},
  "medium_count": {n},
  "low_count": {n},
  "total_count": {n},
  "timestamp": "{ISO datetime}"
}

Error Handling

• Draft file not found: Stop. Tell user the exact path checked.
• Voice guide not resolvable: Stop. Tell user to pass --voice-guide <path> explicitly.
• Judge prompt file missing: Install error. Tell user: "Voice Gate judge prompt missing at voice-gate/judge-prompt.md. Re-install the skill."
• Draft exceeds ~40K words: Proceed, but add a note at the top of the report: "Draft exceeds the comfortable review window; the report may be partial."
• Voice guide lacks numbered rules: The judge falls back to editorial-principle citations. Add a note at the top of the report: "Voice guide lacks numbered rules — citations use editorial principles only."

Chain State

Reads from: the draft, the voice guide, the persona (if present), voice-gate/judge-prompt.md Writes to:

• <draft-path-stem>.VOICE-GATE.md — the editorial report (alongside the draft)
• ~/.kai-marketing/gates/{date}-{slug}-voice.json — log entry

Read by: Human editor who opens the report for triage. Optionally re-read by /content-retro downstream.

When to Use This Skill

Use it:

• For any client with a written voice guide (outputs/personas/*-writing-guide.md).
• After /content-gate passes — it is the subjective complement to the rule-based gate.
• On blog posts, LinkedIn articles, newsletters, long-form content.
• Any time a reviewer has flagged "this doesn't sound like them" on prior drafts.

Skip it:

• Ad copy (voice matters less than claim-compliance; /content-gate is enough).
• Technical documentation, product release notes.
• Content without a written voice standard — the gate has nothing to score against.
• When the voice owner is about to read the draft themselves within an hour.

Pipeline Position

draft agent  →  /content-gate (rule-based)  →  /voice-gate (subjective)  →  human review  →  publish