---
name: voice-mirror
description: "Capture the operator's authorial voice from their own writing and apply it to agent-drafted content. Activate when the operator asks to tag historical content as human-authored, to distil a style profile, to retrieve voice exemplars for a drafting task, or to record their edit on an agent draft as feedback. Other drafting skills (email composition, Postiz publisher, property-brochure, prospectus) call `voice-retrieve-conditioning` transparently — `voiceMirror: false` in the calling skill's frontmatter opts out."
---

# Voice Mirror

Distil the operator's own voice from the content they have actually written, and condition agent drafts on it so generated copy reads as theirs. Anthropic models cannot be fine-tuned; voice mimicry comes from in-context conditioning — a style card plus a handful of real exemplars. The 1M context window makes this affordable.

The skill is built on five deterministic MCP tools served by the `writer-craft` plugin's MCP server (`premium-plugins/writer-craft/mcp/`):

| Tool | Purpose |
|------|---------|
| `voice-tag-content` | Stamp historical or new content nodes with `authorshipMode` and operator-supplied `format`. Bulk-tags arrays of node ids. |
| `voice-distil-profile` | Walk the operator's `human-only` corpus for a given `format` and produce a `:VoiceProfile {styleCard, generatedAt, corpusSize, feedbackEntries, format}` node. Without a `format`, enumerates all formats present in the corpus and distils each. |
| `voice-retrieve-conditioning` | Return `{styleCard, exemplars[]}` for a drafting brief. Requires `brief.format` (one of the six corpus formats). K=5 for short-form, K=15 for long-form. Token-budget bounded. |
| `voice-record-feedback` | When the operator edits an agent draft, write a `:VoiceEdit {originalText, editedText, intent, occurredAt, format}-[:FEEDBACK_FOR]->(:VoiceProfile {format})` node. The `intent` field is a Haiku-summarised diff. |
| `voice-ingest-session-text` | Write operator turns from the current session as `:Message {format:'text', authorshipMode:'human-only'}` corpus nodes. The agent reads its own operator turns from context and passes them as `turns`. Deduplicates via `contentHash`. Invoked on demand when the operator asks to capture this session's voice. |

## Surface — admin only, never delegated

All five tools are admin-allowlisted (`embed: ["admin"]`); they exist only on the admin agent's tool surface. No specialist carries them, by design — `format` and `authorshipMode` are editorial choices the operator makes, so voice-mirror is an operator-interactive admin flow, not a step a specialist runs unattended.

This matters most right after an ingest. When a specialist (the librarian) files a document and the operator then asks to tag it — "mark that as me / human-only / marketing-copy" — the tagging is yours to run, not the specialist's. The specialist cannot call `voice-tag-content` and will hand back the created node's identifier instead. Take that id and run `voice-tag-content` here. If the id is not in context (a later turn, the librarian's return scrolled off), fall back to the unknown-authorship query in the backfill flow below to find the just-filed node. Never route the tag back into a specialist; a specialist reporting "voice-tag-content is not in my tools" is the boundary working as intended, not a failure to escalate.

## When to activate

Activate when the operator says any of:

- **"Tag this as me" / "I wrote that" / "mark these as human-only".** Drives `voice-tag-content`.
- **"Build my voice profile" / "distil my style" / "rebuild the voice mirror".** Drives `voice-distil-profile`.
- **"Read my writing first" / "draft this in my voice" — when the operator is asking for a hand-written-quality draft, not a generic AI reply.** Drives `voice-retrieve-conditioning`; the calling drafting skill is the actual surface, this skill is the conditioning input.
- **"Use my edit as a teaching example" / "remember how I changed that".** Drives `voice-record-feedback`.
- **"Review my historical writing and tag it" / "start the backfill".** Drives the interactive backfill flow described below.
- **"Capture my voice from this chat" / "ingest this session" / "learn how I write from this conversation".** Drives the on-demand session-text capture flow described below.

Do **not** activate for:

- Writing-craft review tasks (`prose-craft`, `review-prose`, etc.). Those are critique skills, not voice-capture.
- Public-figure voice mimicry. Out of scope — see the `## Out of scope` section.
- Audio voice cloning. Different domain entirely.

## Corpus formats

Voice profiles are segmented by content format. The closed enum is:

| Format | Operator picks for |
|--------|--------------------|
| `text` | `:Message` nodes; the operator's session turns, captured on demand via `voice-ingest-session-text` when the operator asks to capture this session's voice |
| `email` | Email threads stored as `:KnowledgeDocument {source:'email'}` or `:ConversationArchive {source:'email'}` |
| `social-post` | `:SocialPost` nodes |
| `article` | Long-form `:KnowledgeDocument` the operator considers an article |
| `note` | Short-form `:KnowledgeDocument` the operator considers a note |
| `marketing-copy` | Any node the operator considers marketing copy |

Format is editorial — the operator picks it per node when calling `voice-tag-content`. The tool does not infer it.

## Flow — backfill review (one-shot session)

Run when the operator first installs voice-mirror, then whenever they want to refresh the corpus.

### 1. Pick a corpus stream

The operator's authored content lives in two stream shapes that the backfill UX handles differently:

- **Discrete documents and posts** — `:KnowledgeDocument` (covers email threads via `source:'email'` since Task 321), `:SocialPost`, and one-off `:Message` nodes. Per-item tagging with previews.
- **Chat archives** — conversation-document `:KnowledgeDocument` nodes (those carrying `conversationIdentity`) with their child `:Section` chunks. Per-conversation tagging because chunking happens server-side and the operator owns whole conversations, not individual chunks. Chat is the highest-leverage corpus — the unguarded voice that email rarely captures.

Ask the operator which stream to backfill first. Default to chat archives when the account has any conversation-document `:KnowledgeDocument` nodes, because that's where voice signal is strongest.

### 2a. Discrete documents — paginate in batches of 10

Query for `:KnowledgeDocument | :SocialPost | :Message` nodes belonging to this operator's account whose `authorshipMode` is `unknown`. Order by `dateSent | datePublished | dateCreated` descending — most recent first. For each batch, surface a numbered list with: source label, date, recipient or topic, and a one-line preview (first ~120 chars of body). Operator commands name both mode and format:

- `1-10 human-only article` — tag every item in the batch as `human-only` with format `article`.
- `1,3,7 human-only email` — tag a subset with mode + format.
- `2 human-led-agent-assisted note` — single-item.
- `5 agent-led-human-reviewed marketing-copy` — single-item.
- `skip` — leave the batch as `unknown` and advance.
- `stop` — exit the backfill; the next session resumes from where the operator left off.

`format` is required on every command; the tool will not infer it. If the operator omits the format, ask before tagging. Bulk-tag via `voice-tag-content` once per operator response. Emit `[voice-tag] mode=<mode> format=<format> count=<n>` per write.

### 2b. Chat archives — paginate per conversation-document parent

For each conversation-document `:KnowledgeDocument` (with `conversationIdentity` set) that has at least one `:Section` chunk whose `authorshipMode` is `unknown`, surface: source file, participant names, message count, date range, and a one-line summary. Offer:

- `human-only` — tag every child `:Section` chunk in this conversation as `human-only`.
- `mixed` — open the conversation for per-chunk tagging (rare; only when the archive contains multiple authors on the operator's side).
- `not me` — tag every chunk as `agent-only` (e.g. a Slack channel where the operator only forwarded other people's messages).
- `skip` / `stop` — same semantics as 2a.

Bulk-tag via `voice-tag-content` with the list of `:Section` element IDs the conversation-document contains, passing `format='text'` (chat archives are unambiguously text-format). The skill emits `[voice-tag] mode=<mode> format=<format> count=<chunk-count>` once per conversation.

Authorship at conversation granularity is a deliberate UX trade-off: chunks within a conversation almost always share the same operator's voice, and per-chunk tagging at archive scale would burn the operator's attention. The `mixed` opt-in covers the rare case where it matters.

### 3. Distil when the corpus crosses threshold

After each backfill batch, check whether the qualifying corpus (`authorshipMode IN ['human-only', 'human-led-agent-assisted']`) for any format has grown ≥20% since the last `:VoiceProfile.corpusSize` for that format (or ≥1 entry if no profile exists for that format). If yes, offer to run `voice-distil-profile` immediately. The operator can defer; the next scheduled distillation will pick it up.

## On-demand text-format capture (session turns)

Operator turns are captured into the `text` corpus on demand — when the operator asks to capture this session's voice, never automatically. There is no SessionEnd hook; the operator is in the loop.

When the operator says "capture my voice from this chat" (or similar):

1. Read the operator's own turns from the live conversation context — the user messages already in this session.
2. Call `voice-ingest-session-text` with those turns as the `turns` array. The tool filters out slash commands, harness injections (`<system-reminder>`), and large paste blocks, deduplicates via SHA256 content hash, and writes each new turn as a `:Message {format:'text', authorshipMode:'human-only'}` node.
3. The tool triggers an incremental `text`-format distillation if the corpus grew ≥20% since the last profile.

This runs only on the admin seat (the tool is admin-allowlisted). Accounts without a voice profile degrade gracefully — capture simply populates the corpus for the first distillation.

## Flow — drafting-time conditioning

Drafting skills (email composition, Postiz, property-brochure, prospectus) call `voice-retrieve-conditioning` transparently before assembling their prompt. The skill takes a brief — `{topic, format, length, register}` — where `format` is the target corpus format and returns:

```yaml
styleCard: |
  sentenceLengthDistribution: short-heavy (median 12 words)
  register: warm-professional, British, contraction-friendly
  favoured: ["properly", "the right thing", "happy to"]
  avoided: ["circle back", "synergy", "leverage"]
  taboos: ["per my last email", "kind regards"]
  opening: drop the salutation if the thread is mid-flow; otherwise "Hi <name>,"
  closing: "Best, Neo" — no signature block
exemplars:
  - source: Email to Sarah Knight, 2026-04-12, re: lease draft
    body: "…actual operator-written paragraph…"
  - source: SocialPost on LinkedIn, 2026-03-30
    body: "…"
```

Drafting skills inject both blocks into their prompt. Opt-out is per-skill: declare `voiceMirror: false` in the skill's frontmatter and the calling site skips the fetch. Default is on.

The tool returns `{styleCard, exemplars, status}` with a discriminated `status` (Task 493):

- **`ok`** — a profile and/or exemplars were returned; inject both blocks.
- **`no-data`** — the lookup ran but no `:VoiceProfile` exists for this format and the corpus is empty (too small, or distillation never run). Fall back to default register; if the operator asks, this is the only state where you say "you have no voice profile yet".
- **`error`** — the lookup failed (the payload carries an `error` message). Fall back to default register *exactly as for no-data* so drafting never crashes — but **never** tell the operator they have no profile; the profile state is unknown because the lookup errored.

In all three states drafting proceeds: `no-data` and `error` both degrade to the default register, no draft refusal. The distinction matters only for what you tell the operator about *why* their voice was not applied.

Emit `[voice-retrieve] task=<brief> format=<format> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` per call.

## Flow — feedback capture

When the operator edits an agent draft (in the email composer's edit loop, or in any drafting skill that supports inline edits), capture the diff:

1. The calling skill passes `{originalText, editedText, format}` to `voice-record-feedback`.
2. The tool runs a Haiku diff summarisation to produce an `intent` field — a one-sentence description of what the operator changed and why. Example intents: "shorter and dropped the apology", "switched to first person", "removed sign-off", "added a specific date".
3. The tool writes `(:VoiceEdit {originalText, editedText, intent, occurredAt, userId, accountId, format})-[:FEEDBACK_FOR]->(:VoiceProfile {format})` for the operator's profile.

Feedback accumulates between distillations. The next `voice-distil-profile` run reads every `:VoiceEdit` linked to the profile and feeds the intents into the style-card refinement.

Emit `[voice-record-feedback] userId=<id> format=<format> intent="<haiku-summary>" diffBytes=<n>`.

## Distillation cadence

`voice-distil-profile` re-runs per format when **either**:

- the `human-only` corpus for that format has grown ≥20% since the last `:VoiceProfile.corpusSize` for that format, OR
- 30 days have passed since `:VoiceProfile.generatedAt` for that format.

A re-run within the 30-day window with <20% growth is a no-op — the tool returns the existing profile unchanged and emits `[voice-distil] skip reason=below-threshold format=<format>`.

The triggering surface is the skill, not a scheduled job. Distillation runs on demand: at the end of a backfill batch, when the email composer notices stale-profile narration, or when the operator says "rebuild my voice profile".

### Amend mode (single-document update)

Activate when the operator names one or more specific documents and wants them folded into their voice profile right now — e.g. **"I just published this new article, take that into account"**, **"that thread to Sarah is a good example of how I write — fold it in"**, or **"add this essay to my voice profile"**. The full-corpus distil cadence is wrong for "this specific document, now" — the operator's signal is the document choice, not the cadence guard.

Call `voice-distil-profile` with:

- `mode: 'amend'`
- `format: <VoiceFormat>` — required; the operator's per-format profile
- `nodeIds: [<elementId>, ...]` — the documents the operator picked (one or more)

The tool returns `{existingStyleCard, exemplars[], feedbackIntents[], eligible, ineligible}`. Compare the named exemplars against the prior card and the recent edit intents, then choose:

- **Material delta** — compose an updated YAML and call `mode: 'write'` with `styleCardYaml` and `amendedFromNodeIds: [<elementId>, ...]` listing the documents that actually moved the card. The write bypasses the cadence guard and adds `LEARNED_FROM` edges to those documents (pre-existing edges remain).
- **No material delta** — reply to the operator in-turn ("nothing in that article shifts your voice card; the prior profile still applies"). Do not call `mode: 'write'`. `generatedAt` only advances on a write.

When `eligible=0` (every named document failed the predicate) surface the `ineligible[]` payload to the operator naming the per-id reason (`node-not-found`, `wrong-account`, `ineligible-authorship-mode`, `trashed`, `ineligible-label`) rather than silently no-op. Most commonly this means the documents are tagged as `agent-only` and need re-tagging via `voice-tag-content` before they can amend a profile.

Amend mode does not apply to the on-demand session-text capture path. Session-text ingest stays on the full-corpus path; amend is operator-initiated only.

## Per-operator scope

One `:VoiceProfile` per `(accountId, userId, format)`. Multi-author accounts (an agency with several operators) get one profile per person per format. Identity is the `(accountId, userId, format)` triple, enforced by the schema constraint.

## Observability

| Tag | When |
|-----|------|
| `[voice-tag] mode=<mode> format=<format> nodeId=<id> count=<n>` | Every tag write. |
| `[voice-distil] userId=<id> format=<format> corpusSize=<n> generatedAt=<iso> feedbackEntries=<n>` | Each distillation. |
| `[voice-distil] skip reason=<below-threshold\|recent> format=<format>` | When the cadence guard fires. |
| `[voice-distil] mode=amend userId=<id> format=<format> nodeIds=<count> existingProfile=<elementId\|none> eligible=<n> ineligible=<n> exemplars=<n>` | Each amend-mode call. `eligible=0` means surface `ineligible[]` to the operator, never silently no-op. |
| `[voice-distil] mode=write userId=<id> format=<format> amended=true amendedFromNodeIds=<count> ...` | Amend-write fired (operator-initiated update persisted). |
| `[voice-retrieve] task=<topic> format=<format> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` | Each retrieval. |
| `[voice-record-feedback] userId=<id> format=<format> intent="<haiku-summary>" diffBytes=<n>` | Each feedback write. |
| `[voice-ingest-session-text] sessionId=<id> adminUser=<id> turns=<n> bytes=<n> skipped=<m>` | On-demand session-text capture. |

**Confirms working:** `[voice-retrieve] exemplarCount≥1` precedes every drafting-skill prompt assembly when the calling skill has not opted out. `[voice-distil]` appears at least once per 30-day window per active format per operator. `[voice-ingest-session-text] turns≥1` appears when the operator asks to capture a session's voice.

**Indicates failure:** `[voice-retrieve] exemplarCount=0` with non-empty corpus → similarity index broken; `[voice-distil] error …` → corpus walk or LLM call failed; absence of `[voice-record-feedback]` after an operator-edit-then-send flow → feedback loop is dead.

**Diagnostic path:**

```
journalctl -u maxy-code | grep -E '\[voice-(tag|distil|retrieve|record-feedback|ingest-session-text)\]'
```

Filter by `userId=<id>` for per-operator drill-down.

## Out of scope

- Voice blending across multiple authors (no "Joel + Neo combined voice").
- Style transfer from public-figure corpora — voice-mirror only learns from the operator's own writing.
- Audio voice cloning / speech synthesis — different domain.
- Auto-tagging legacy content via heuristics — backfill is operator-driven only; the agent never guesses authorship.
- Admin-UI editing of the `styleCard` — operator edits via `database-operator` for now. Surfacing this in a dedicated UI is a follow-up task.

## Dependencies

- **Memory plugin's graph-write gate** is the single write boundary; new tools route through it, never bypass.
- **Haiku LLM call path** (already used by `memory-classify`) is reused for diff-intent summarisation.
- **`:AdminUser` must exist** for the operator before distillation runs. Personal-mode operators with `Person {role: "admin-personal"}` need to be promoted to an `:AdminUser` first — out of scope here.
