Voice Generate

Voice Generation Skill

Generate text in a user's extracted writing voice.

Core Principle: Source Material Framing

The single largest variable in output quality is how source material is framed in the prompt. Material framed as "raw notes I'm still thinking through" produces text that feels like thinking. Material framed as summaries produces reporting.

Always frame user-provided source material as raw notes unless the user explicitly requests otherwise.

Required TodoWrite Items

1. voice-generate:profile-loaded - Voice profile read 2. voice-generate:register-selected - Register chosen 3. voice-generate:source-framed - Material framed as notes 4. voice-generate:generated - Text produced 5. voice-generate:review-dispatched - Sent to review agents

Step 1: Load Voice Profile

PROFILE_DIR="$HOME/.claude/voice-profiles/{name}"

Read in order: 1. extraction.md - Core voice features 2. registers/{register}.md - Active register 3. craft-rules.md - Shared craft techniques (if exists) 4. banned-phrases.md - Anti-patterns to avoid (if exists)

Check for per-project override:

if [ -f ".voice/override.md" ]; then
  # Merge project overrides with profile
fi

Step 2: Register Selection

Load: @modules/register-selection

Select register by: 1. Explicit user request ("use casual register") 2. Context matching from register metadata 3. Default fallback to registers/default.md

Step 3: Frame Source Material

Load: @modules/source-framing

Default framing (always use unless user overrides):

Below are my rough notes on this topic. I'm still thinking
through these ideas. Use them as the raw material for the
piece, not as a structure to follow:

---
{user_provided_source_material}
---

Alternative framings (only if user requests):

• "structured outline" - when user wants to preserve structure
• "key points to cover" - when user provides bullet points
• "conversation to draw from" - when source is a transcript

Step 4: Generation Prompt

Compose the generation prompt:

You are writing a piece in a specific voice. The voice
features below were extracted from the writer's own work.
Follow them as concrete instructions, not suggestions.

## Voice Features

{extraction.md content}

## Active Register: {register_name}

{register content}

## Craft Techniques (apply all)

- Concrete-first: Lead with specific, physical details before
  any abstraction
- Naming: When you describe a pattern in 2+ sentences, compress
  it into a 2-4 word label
- Opening moves: Start mid-thought, with a specific moment, or
  with a counterintuitive claim. Never start with throat-clearing
- Human-moment anchoring: Ground every abstraction in a specific
  scene or lived experience
- Aphoristic destinations: At least one sentence per section
  should be worth repeating out of context

## Banned (never use)

{banned_phrases content, or default list:}
- Em dashes (use commas, colons, semicolons, parentheses)
- "delve", "utilize", "leverage", "facilitate"
- "it's important to note", "in today's world"
- "here's the thing", "let that sink in"
- "furthermore", "moreover", "comprehensive"
- Negation-correction patterns ("This isn't X. This is Y.")

## Source Material

{framed source material from Step 3}

## Task

Write the piece. Follow the voice features precisely. Apply
craft techniques. Do not use any banned phrases. The output
should read as if the writer produced it themselves.

Length: {user_specified or ~same as source material}
Format: {user_specified or prose paragraphs}

Step 5: Post-Generation

After generation: 1. Scan output for banned phrases (auto-fix silently) 2. Check for em dashes (replace with appropriate punctuation) 3. Dispatch to voice-review skill if user wants review 4. Save pre-review snapshot if learning mode is active

Model Routing

• Generation: Use Opus. Tonal shifts, parenthetical

subversion, and subtle voice qualities require the larger model. Sonnet flattens these.

• Banned phrase scan: Can run locally (regex/grep)
• Review agents: Sonnet is sufficient (the prompts are

templated, so Opus tonal range is not needed)

Per-Project Voice

If .voice/override.md exists in the current project:

• Read override content
• Merge with profile (overrides take precedence)
• Note in output: "Applied project voice override"

Exit Criteria

• Text generated in the specified voice
• No banned phrases present
• Craft techniques applied (concrete-first, naming, etc.)
• Source material framed as raw notes
• Review dispatched (if requested)
• Snapshot saved (if learning mode active)

Generation Pipeline Module

End-to-end generation flow from source material to reviewed text.

Pipeline Stages

Source Material
    |
    v
[Frame as raw notes]
    |
    v
[Load profile + register + craft rules]
    |
    v
[Generate with Opus]
    |
    v
[Auto-fix: banned phrases, em dashes]
    |
    v
[Snapshot: pre-review] (if learning active)
    |
    v
[Dispatch review agents] (optional)
    |
    v
[Present advisories to user]
    |
    v
[Apply user decisions]
    |
    v
[Snapshot: post-review] (if learning active)
    |
    v
Final text (user may edit further)
    |
    v
[/voice-learn captures post-edit] (user-triggered)

Auto-Fix Rules (Silent)

Applied immediately after generation, before review:

# Em dash replacement (context-aware)
# Before a clause: use comma or colon
# Parenthetical: use parentheses
# List separator: use semicolons

# Banned phrase removal
# "Furthermore," -> "" (start sentence without it)
# "It's important to note" -> "" (remove entirely)
# "delve" -> "explore" or "examine"
# "utilize" -> "use"
# "leverage" -> "use" or remove
# "comprehensive" -> "thorough" or "complete"
# "robust" -> "solid" or remove
# "seamless" -> "smooth" or remove

Model Routing

Error Recovery

If generation fails quality checks (> 5 hard failures): 1. Re-generate with stronger emphasis on banned phrases 2. If second attempt still fails, present to user with warning 3. Never loop more than twice (prevents infinite retry)

Streaming Considerations

For long-form content (> 1000 words):

• Generate in sections (one per major heading)
• Apply auto-fix per section
• Allow user to review section-by-section or all at once
• Snapshot captures the complete assembled text

Register Selection Module

Choose the appropriate voice register for generation.

Selection Priority

1. Explicit request: User says "use casual register" 2. Context match: Register metadata matches the task 3. Default: Fall back to registers/default.md

Context Matching

Each register file has a ## Context section describing when to use it. Match against the user's stated purpose:

User: "Write a blog post about..."     -> default or narrative
User: "Draft a technical doc for..."   -> technical
User: "Reply to this Reddit thread..." -> casual
User: "Write an email to my team..."   -> professional

Register Loading

PROFILE_DIR="$HOME/.claude/voice-profiles/$PROFILE_NAME"
REGISTER_FILE="$PROFILE_DIR/registers/${REGISTER_NAME}.md"

if [ ! -f "$REGISTER_FILE" ]; then
  echo "Register '$REGISTER_NAME' not found. Available:"
  ls "$PROFILE_DIR/registers/"
  echo "Using default register."
  REGISTER_FILE="$PROFILE_DIR/registers/default.md"
fi

Inheritance

Non-default registers inherit from default unless they explicitly override a section. When loading a non-default register:

1. Read default.md as base 2. Read {name}.md for overrides and additions 3. Merge: override sections replace, additions append

Listing Available Registers

When user asks what registers exist:

echo "Available voice registers for $PROFILE_NAME:"
for f in "$PROFILE_DIR/registers/"*.md; do
  name=$(basename "$f" .md)
  context=$(grep -A1 "^## Context" "$f" | tail -1)
  echo "  $name: $context"
done

Source Framing Module

How source material is framed in the prompt is the single largest variable in output quality. Larger than voice rules. Larger than model choice.

The Framing Lever

When material is framed as "raw notes I'm still thinking through," the output is dramatically better than when framed as "a transcript to draw on" or a bare topic sentence.

The framing changes how the model relates to the material:

• Notes to think through -> text that feels like thinking
• Summaries to report on -> text that feels like reporting
• Transcripts to draw from -> text that feels like paraphrase

Default Framing (always use)

Below are my rough notes on this topic. I'm still working
through these ideas and haven't settled on a final structure.
Use them as raw material for thinking, not as an outline
to follow:

---
{source_material}
---

Write a piece that engages with these ideas in the voice
described above. You don't need to cover everything in the
notes. Follow where the interesting threads lead.

When User Provides Structured Input

If the user gives bullet points or an outline, still reframe as notes:

Below are my working notes. These bullet points represent
threads I'm pulling on, not a structure to reproduce:

---
{bullet_points}
---

When User Provides a Topic Only

If just a topic sentence or phrase:

I want to write about: {topic}

Here's what I'm thinking so far: I don't have notes yet,
but the angle I'm interested in is {topic}. Write an
exploratory piece that discovers its argument as it goes.

Override Framings

Only use these if the user explicitly requests a different relationship to the source material:

"Preserve my structure"

Below is an outline I want to follow. Keep the structure
but write each section in the voice described above:

"Respond to this"

Below is something I'm responding to. Write a response
in the voice described above:

"Expand these points"

Below are key points I want to develop. Expand each one
into full prose in the voice described above: