@rubytech/create-maxy-code 0.1.169 → 0.1.171

package/payload/platform/plugins/writer-craft/skills/voice-mirror/SKILL.md

@@ -1,166 +0,0 @@
----
-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 four 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`. Bulk-tags arrays of node ids. |
-| `voice-distil-profile` | Walk the operator's `human-only` corpus and produce a `:VoiceProfile {styleCard, generatedAt, corpusSize, feedbackEntries}` node. |
-| `voice-retrieve-conditioning` | Return `{styleCard, exemplars[]}` for a drafting brief. 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}-[:FEEDBACK_FOR]->(:VoiceProfile)` node. The `intent` field is a Haiku-summarised diff. |
-
-## 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.
-
-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.
-
-## 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). Offer bulk shortcuts:
-
-- `1-10 human-only` — tag every item in the batch as `human-only`.
-- `1,3,7 human-only` — tag a subset.
-- `2 human-led-agent-assisted` — single-item mode override.
-- `5 agent-led-human-reviewed` — single-item mode override.
-- `skip` — leave the batch as `unknown` and advance.
-- `stop` — exit the backfill; the next session resumes from where the operator left off.
-
-Bulk-tag via `voice-tag-content` once per operator response. Emit `[voice-tag] mode=<mode> 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. The skill emits `[voice-tag] mode=<mode> 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']`) has grown ≥20% since the last `:VoiceProfile.corpusSize` (or ≥1 entry if no profile exists). If yes, offer to run `voice-distil-profile` immediately. The operator can defer; the next scheduled distillation will pick it up.
-
-## 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, register}` — 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.
-
-If the `:VoiceProfile` does not yet exist (corpus too small, or distillation never run), the tool returns `{styleCard: null, exemplars: []}` and the calling skill falls back to its existing default register. No error, no draft refusal.
-
-Emit `[voice-retrieve] task=<brief> 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}` 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, adminUserId, accountId})-[:FEEDBACK_FOR]->(:VoiceProfile)` 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] adminUser=<id> intent="<haiku-summary>" diffBytes=<n>`.
-
-## Distillation cadence
-
-`voice-distil-profile` re-runs when **either**:
-
-- the `human-only` corpus has grown ≥20% since the last `:VoiceProfile.corpusSize`, OR
-- 30 days have passed since `:VoiceProfile.generatedAt`.
-
-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`.
-
-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".
-
-## Per-operator scope
-
-One `:VoiceProfile` per `:AdminUser`. Multi-author accounts (an agency with several operators) get one profile per person. Identity is the `(accountId, adminUserId)` pair, enforced by the schema constraint.
-
-## Observability
-
-| Tag | When |
-|-----|------|
-| `[voice-tag] mode=<mode> nodeId=<id> count=<n>` | Every tag write. |
-| `[voice-distil] adminUser=<id> corpusSize=<n> generatedAt=<iso> feedbackEntries=<n>` | Each distillation. |
-| `[voice-distil] skip reason=<below-threshold\|recent>` | When the cadence guard fires. |
-| `[voice-retrieve] task=<topic\|format> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` | Each retrieval. |
-| `[voice-record-feedback] adminUser=<id> intent="<haiku-summary>" diffBytes=<n>` | Each feedback write. |
-
-**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 `:AdminUser`.
-
-**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)\]'
-```
-
-Filter by `adminUser=<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.
-- Register-segmented profiles (one profile per author, not one per formality level).
-- 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.