@holdyourvoice/hyv 2.0.1 → 2.1.0

package/assets/ai-eliminator-rules.md

@@ -0,0 +1,130 @@
+# AI Eliminator Rules (v2 — 220+ patterns + structural signals)
+
+Use these rules to remove AI-generated cadence without erasing the writer.
+
+## Core Rule
+
+Fix the exact line that drifted. Do not rewrite a whole draft when one sentence
+is the problem. Preserve clean surrounding lines.
+
+## Detection Coverage
+
+The algorithm now detects 220+ named AI writing patterns organized across 31
+composite regex rules, plus structural/rhythmic analysis of: burstiness
+(sentence length variance), paragraph rhythm uniformity, contraction density,
+formal hedging, generic intensifiers, fragment ratio, over-structured list
+patterns, and uniform sentence rhythm within paragraphs.
+
+## Banned Pattern Categories
+
+### Binary reframing & negation (#1, #210-212)
+- "It's not X, it's Y" / "The point isn't X, it's Y"
+- "You don't need X, you need Y"
+- "Not just X, but Y" / "Not only... but also"
+
+### Staccato drama (#2, #95, #96)
+- Short punchy sentence runs: "No X. No Y. Just Z."
+- Perfectly even sentence rhythm throughout paragraphs
+- Three short sentences in a row (performance cadence)
+
+### Landscape/era grandstanding (#3, #181-188)
+- "In today's fast-paced world" / "ever-evolving landscape"
+- "Now more than ever" / "as never before"
+- "Has never been more important"
+- "In the digital age" / "new era of X"
+- "The rise of X" / "increasingly + adjective"
+
+### Truth/reality posturing (#22, #110, #161-163)
+- "The truth is" / "the reality is" / "here's the truth"
+- "The harsh/ugly/brutal reality" / "real talk"
+- "Brutal honesty" / "reality check"
+
+### Hedging & non-committal (#4, #53-55, #89, #197-199)
+- "It depends, but" / "no one-size-fits-all"
+- "It can be tempting to" / "you might be tempted to"
+- "In many ways" / "at first it might seem"
+
+### Transitions & balance (#7, #38-40, #81, #91, #203)
+- "On the one hand / on the other hand"
+- "On the flip side" / "that said" / "however"
+- "Moreover / furthermore / in addition" chains
+- "At first glance vs on closer inspection"
+
+### Let's/invitation patterns (#5, #63-65, #80, #127)
+- "Let's dive in" / "let's explore" / "let's break it down"
+- "Delve into" / "dive deeper" / "deep dive"
+- "Navigate the complex landscape"
+
+### Empathy opener (#21, #74-75, #107, #164-165)
+- "It's easy to feel X" / "you're not alone"
+- "You're not imagining it" / "you deserve"
+- "Shouting into the void"
+
+### Founder/thought-leader cadence (#72-73, #104-109)
+- "Here's the thing" / "and honestly?"
+- "Here's the kicker" / "the part most people miss"
+- "What nobody's saying" / "the best part?"
+- "Same X. Better Y." / "the moment X becomes Y"
+
+### Marketing verbs (#61-62, #83, #114-117, #145-150)
+- "Unlock the power of" / "harness the power of"
+- "Transform/elevate/take to the next level"
+- "Master the art of" / "game-changer"
+- "Supercharge / turbocharge / on steroids"
+
+### Journey/destination clichés (#59, #84, #122, #144, #214-215)
+- "X isn't a destination; it's a journey"
+- "No matter where you are on your journey"
+- "Embark on" / "you're still early" / "it's still day one"
+
+### Metaphor clusters (#18, #120-121, #159-160, #167-168, #173-180)
+- "Beacon / lighthouse / tapestry / symphony / tides"
+- "Silent killer / hidden gem / tip of the iceberg"
+- "North star / double-edged sword / blessing and a curse"
+- "Noise vs signal" / "X is the new Y"
+- "Flood / avalanche / tsunami of X"
+
+### Guide/article framing (#11-13, #27-28, #136-138)
+- "You're in the right place" / "here's a step-by-step guide"
+- "First, second, third" / "key takeaways" / "actionable tips"
+- "In this article/guide/post" / "this piece explores"
+
+### Wrapping/closing (#9, #14-15, #51-52, #66, #93, #103, #189, #217)
+- "At the end of the day" / "the bottom line is"
+- "In conclusion / in summary / to recap"
+- "Let that sink in" / "only time will tell"
+- "Curious what others think" / "let me know if you need help"
+
+### UX/business buzzwords (#92, #123-126, #155-157)
+- "Robust, scalable, innovative, impactful"
+- "Seamless experience" / "frictionless journey"
+- "Pain points" / "wealth of insights"
+
+### Story/temporal templates (#17, #32-33, #113, #216, #218-219)
+- "Imagine this / picture this"
+- "Storytelling has been around for centuries"
+- "Little did I know" / "at first I was skeptical"
+- "The best time was X, the second-best time is now"
+
+## Structural Signals (Beyond Individual Words)
+
+- **Low burstiness**: Sentence lengths all similar (coefficient of variation < 0.35)
+- **Mechanical paragraphs**: All paragraphs nearly identical sentence count
+- **Over-structured lists**: Rigid 3-item lists throughout
+- **Uniform paragraph rhythm**: Most sentences fall in 12-22 word range
+- **Low contractions**: < 0.8 contractions per 100 words (overly formal)
+- **Formal hedging density**: 2+ institutional hedging phrases
+- **Generic intensifiers**: 3+ "remarkably/incredibly/amazingly" instances
+- **No fragments**: Zero sentence fragments in 20+ sentences (over-polished)
+
+## What To Do Instead
+
+- Start from rough private-note material: an exact edit, meeting fragment,
+  dashboard annoyance, customer confusion, half-remembered sentence, or internal
+  contradiction.
+- Let the idea move because the logic moves, not because line breaks perform.
+- Prefer concrete scenes, mechanisms, quoted language, and specific stakes.
+- Let some pieces end on a detail, hesitation, unresolved thought, or awkwardly
+  specific observation.
+- If a line sounds like a maxim, a carousel, or a model trying to be sharp,
+  make it plainer and more grounded.

package/assets/ai-eliminator-skill.md

@@ -0,0 +1,63 @@
+---
+name: ai-writing-eliminator
+description: Use when the user wants to remove AI writing patterns, humanize a draft, make prose less generic, scan for AI cadence, or rewrite only the lines that sound synthetic.
+---
+
+# AI Writing Eliminator (v2)
+
+This skill removes machine-shaped writing without destroying the draft. The
+algorithm now detects 220+ named AI writing patterns across 31 composite regex
+rules, plus 9 structural/rhythmic signals (burstiness, paragraph uniformity,
+contraction density, formal hedging, intensifier overuse, fragment ratio,
+staccato detection, over-structured lists, uniform sentence rhythm).
+
+## Non-Negotiables
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+Use the helper script when a draft is in a file:
+
+```bash
+hyv scan <draft path>
+```
+
+For pasted text, apply the same rules manually from
+`assets/ai-eliminator-rules.md`.
+
+## Repair Prompt
+
+When a model rewrite is needed, generate a line-level prompt:
+
+```bash
+hyv rewrite-prompt \
+  --profile .hold-your-voice/voice-profile.json \
+  <draft path>
+```
+
+If there is no profile, still repair the AI patterns, but do not claim the
+result is voice-matched.
+
+## Bad Fixes
+
+Reject fixes that:
+
+- turn the draft into a tidy founder post
+- make every paragraph land as a lesson
+- replace a concrete scene with an abstract principle
+- use dramatic line breaks to fake rhythm
+- make the writer sound more professional but less specific
+

package/assets/chatgpt-instructions 2.txt

@@ -0,0 +1,8 @@
+when i ask you to "write in my voice" or "rewrite this in my voice":
+
+- read `~/.hyv/voice.md` for my voice profile
+- run `hyv rewrite --text "<text>"` to get the structured prompt
+- execute the prompt and rewrite the text
+- match my rhythm, vocabulary, and patterns exactly
+- never use words i avoid
+- present the rewritten version

package/assets/chatgpt-instructions 3.txt

@@ -0,0 +1,8 @@
+when i ask you to "write in my voice" or "rewrite this in my voice":
+
+- read `~/.hyv/voice.md` for my voice profile
+- run `hyv rewrite --text "<text>"` to get the structured prompt
+- execute the prompt and rewrite the text
+- match my rhythm, vocabulary, and patterns exactly
+- never use words i avoid
+- present the rewritten version

package/assets/chatgpt-instructions.txt

@@ -0,0 +1,8 @@
+when i ask you to "write in my voice" or "rewrite this in my voice":
+
+- read `~/.hyv/voice.md` for my voice profile
+- run `hyv rewrite --text "<text>"` to get the structured prompt
+- execute the prompt and rewrite the text
+- match my rhythm, vocabulary, and patterns exactly
+- never use words i avoid
+- present the rewritten version

package/assets/claude-code-skill 2.md

@@ -0,0 +1,24 @@
+## Hold Your Voice — automated voice rewriting
+
+when the user asks to "write in my voice", "rewrite this in my voice", or "make this sound like me":
+
+1. read their voice profile at `~/.hyv/voice.md`
+2. run `hyv rewrite --text "<their text>"` to generate a structured rewrite prompt
+3. execute the prompt — rewrite the text yourself using your own llm
+4. present the rewritten text
+5. when the user accepts it, run `hyv reinforce original.md edited.md` to teach the system
+
+### available commands
+
+- `hyv scan <file>` — check a draft for voice drift and ai patterns
+- `hyv rewrite <file>` — generate a rewrite prompt for your llm
+- `hyv validate <file>` — verify a rewrite matches the voice profile
+- `hyv reinforce <original> <edited>` — teach the system what was accepted
+- `hyv sync` — refresh cached profiles and rules
+- `hyv status` — show auth and plan info
+
+### important
+
+- hyv never calls an llm. it generates prompts you execute yourself.
+- voice profiles live at `~/.hyv/voice.md`
+- always call `hyv validate` after rewriting to verify the result

package/assets/claude-code-skill.md

@@ -0,0 +1,24 @@
+## Hold Your Voice — automated voice rewriting
+
+when the user asks to "write in my voice", "rewrite this in my voice", or "make this sound like me":
+
+1. read their voice profile at `~/.hyv/voice.md`
+2. run `hyv rewrite --text "<their text>"` to generate a structured rewrite prompt
+3. execute the prompt — rewrite the text yourself using your own llm
+4. present the rewritten text
+5. when the user accepts it, run `hyv reinforce original.md edited.md` to teach the system
+
+### available commands
+
+- `hyv scan <file>` — check a draft for voice drift and ai patterns
+- `hyv rewrite <file>` — generate a rewrite prompt for your llm
+- `hyv validate <file>` — verify a rewrite matches the voice profile
+- `hyv reinforce <original> <edited>` — teach the system what was accepted
+- `hyv sync` — refresh cached profiles and rules
+- `hyv status` — show auth and plan info
+
+### important
+
+- hyv never calls an llm. it generates prompts you execute yourself.
+- voice profiles live at `~/.hyv/voice.md`
+- always call `hyv validate` after rewriting to verify the result

package/assets/cursor-rules 2.md

@@ -0,0 +1,12 @@
+# Hold Your Voice — Cursor Rules
+
+when writing or rewriting content, match the voice profile below. do not use AI-slop words (delve, leverage, tapestry, in today's fast-paced, not just X but Y, etc.). match rhythm, vocabulary, and sentence patterns from the profile.
+
+your voice profile is at `~/.hyv/voice.md`. load it and use it as your writing guide.
+
+when the user says "rewrite in my voice", "make this sound like me", or similar:
+
+1. run: `hyv rewrite --text "<text>"`
+2. the cli generates a structured rewrite prompt
+3. execute the prompt yourself — rewrite the text matching the voice profile
+4. present the result

package/assets/cursor-rules 3.md

@@ -0,0 +1,12 @@
+# Hold Your Voice — Cursor Rules
+
+when writing or rewriting content, match the voice profile below. do not use AI-slop words (delve, leverage, tapestry, in today's fast-paced, not just X but Y, etc.). match rhythm, vocabulary, and sentence patterns from the profile.
+
+your voice profile is at `~/.hyv/voice.md`. load it and use it as your writing guide.
+
+when the user says "rewrite in my voice", "make this sound like me", or similar:
+
+1. run: `hyv rewrite --text "<text>"`
+2. the cli generates a structured rewrite prompt
+3. execute the prompt yourself — rewrite the text matching the voice profile
+4. present the result

package/assets/cursor-rules.md

@@ -0,0 +1,12 @@
+# Hold Your Voice — Cursor Rules
+
+when writing or rewriting content, match the voice profile below. do not use AI-slop words (delve, leverage, tapestry, in today's fast-paced, not just X but Y, etc.). match rhythm, vocabulary, and sentence patterns from the profile.
+
+your voice profile is at `~/.hyv/voice.md`. load it and use it as your writing guide.
+
+when the user says "rewrite in my voice", "make this sound like me", or similar:
+
+1. run: `hyv rewrite --text "<text>"`
+2. the cli generates a structured rewrite prompt
+3. execute the prompt yourself — rewrite the text matching the voice profile
+4. present the result

package/assets/economic-drift-voice.md

@@ -0,0 +1,42 @@
+# Economic Drift Voice
+
+Economic Drift is the default Shashank voice profile when the user asks for
+"my voice" and no fresher project samples are available. Do not force it onto a
+different writer when their own samples exist.
+
+## Philosophy
+
+High-signal, low-friction writing. The reader should get a lot without working
+hard. The tone feels like a private conversation with someone smart, slightly
+cynical, and not performing for approval.
+
+## Style
+
+- Open with a concrete observation, moment, mechanism, or pattern.
+- Avoid lesson openers, question openers, inspirational claims, and generic
+  category summaries.
+- Use contrarian tension only when the real point is uncomfortable, not for
+  cheap shock.
+- Mix simple language with dense thinking.
+- Let sentence length vary naturally. No theatrical staccato.
+- Favor rough private-note texture: exact edits, customer confusion, dashboard
+  annoyances, meeting fragments, internal contradictions.
+- Do not turn every piece into a tidy lesson. Some endings should stop on a
+  detail or unresolved thought.
+- Use lowercase when writing in Shashank's deliberate social-writing style,
+  unless the user or target format asks otherwise.
+
+## Hard Bans
+
+- `here's the thing`
+- `let's be honest`
+- `at the end of the day`
+- `which is another way of saying`
+- `in other words`
+- `the moment x becomes y`
+- `same x. better y.`
+- motivational poster energy
+- screenshot-ready punchline cadence
+- generic founder advice
+- bullets, hashtags, emojis, and bold emphasis in social prose unless requested
+

package/assets/hold-your-voice-skill.md

@@ -0,0 +1,174 @@
+---
+name: hyv-hold-your-voice
+description: "Use when the user wants Hold Your Voice-style writing help across any project: build a voice profile from samples, match a writer's voice, remove AI-writing drift, rewrite drafts without flattening voice, or preserve project-specific writing style."
+---
+
+# Hold Your Voice
+
+This is the orchestration skill. Use the narrower `voice-matcher` and
+`ai-writing-eliminator` skills when a task is only one half of the workflow.
+
+## Core Doctrine
+
+- Hold Your Voice is not a generic AI humanizer. It is a voice-preservation
+  layer around the writing.
+- The benchmark is the writer's own samples, not a universal "good writing"
+  style guide.
+- Trust samples over stated preferences when they disagree.
+- Rewrite only the lines that fail the voice or AI-pattern check.
+- Preserve surrounding text unless the user explicitly asks for a full rewrite.
+- Rough private-note texture beats polished founder cadence.
+
+## Workflow
+
+1. Identify the target writer and output format.
+2. Find or ask for source samples. Prefer real writing from the current project:
+   posts, emails, essays, docs, landing copy, changelog notes, founder notes.
+3. Build a profile when no current profile exists:
+
+   ```bash
+   hyv profile \
+     --name "project voice" \
+     --out .hold-your-voice/voice-profile.json \
+     <sample paths>
+   ```
+
+4. Scan the draft:
+
+   ```bash
+   hyv scan \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+   Passing `--meta` skips patterns the system has learned are not applicable.
+
+5. Rewrite by line, not by vibe:
+
+   ```bash
+   hyv rewrite-prompt \
+     --profile .hold-your-voice/voice-profile.json \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+6. Verify by rescanning the revised draft.
+
+## Output Standard
+
+When returning prose to the user, lead with the finished writing. Keep process
+notes short. If you changed only flagged lines, say that plainly.
+
+For project work, store generated profiles under:
+
+```text
+.hold-your-voice/voice-profile.json
+```
+
+Do not store private samples inside the plugin folder. Keep project-specific
+profiles inside the project that owns the writing.
+
+## Auto-Improvement (default)
+
+The profile **evolves automatically** after every accepted writing session. No
+manual reinforce or update commands needed.
+
+### How it works
+
+After the user accepts a revision, run **one command**:
+
+```bash
+hyv profile-evolve \
+  --original <original draft file> \
+  --accepted <accepted/output draft file> \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--new-samples <paths>` to merge new writing samples in the same step.
+Optional: `--meta <path>` if you need a custom meta file location (defaults to
+`voice-profile.meta.json` alongside the profile).
+
+This does three things simultaneously:
+
+1. **Signal extraction** — diffs original vs accepted to find which AI patterns
+   the user agreed with (`patterns_accepted`) vs overrode (`patterns_overridden`).
+2. **Temporal meta update** — each pattern now tracks `first_seen`,
+   `last_confirmed`, `contradictions`, `confidence` (0.0–1.0), and status
+   (`active` / `declining` / `stale`). Accepted signals boost confidence.
+   Overrides penalize it. Untouched patterns slowly decay.
+3. **Profile stat merge** — sentence length, paragraph shape, and opening moves
+   use weighted rolling averages so the voice benchmark improves with every
+   session.
+
+### Pattern lifecycle
+
+- **Active** — confidence ≥ 0.30, last confirmed within 14 days. These
+  patterns fire during scans.
+- **Declining** — 3+ contradictions and confidence < 0.30. Still tracked
+  but no longer flagged in scan output.
+- **Stale** — 5+ contradictions and confidence < 0.15, or untouched for
+  > 14 days. Archived; does not fire.
+
+This means after a few days of usage:
+
+- Patterns the user consistently accepts (e.g., "inflated_verbs") become
+  high-confidence and reliably flag real AI drift.
+- Patterns the user consistently ignores (e.g., "the user's writing style
+  uses landscape-era phrasing intentionally") quietly fade out.
+- The profile's sentence/paragraph stats converge on the actual voice.
+
+### Check learning state
+
+```bash
+hyv profile-status \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--write-voice voice.md` produces the human-readable voice profile
+with confidence bars per pattern.
+
+### Auto-sync to cloud (daily)
+
+`profile-evolve` automatically tries to sync to Cloudflare R2 after each
+evolution. Sync only happens if:
+
+- The env vars `HYV_R2_ACCESS_KEY_ID`, `HYV_R2_SECRET_ACCESS_KEY`,
+  `HYV_R2_ENDPOINT`, `HYV_R2_BUCKET` are set.
+- The last sync was more than 23 hours ago (no wasteful pushes).
+- The payload is under 1MB (safety cap).
+
+To set up one-time:
+
+```bash
+export HYV_R2_ACCESS_KEY_ID="your-access-key"
+export HYV_R2_SECRET_ACCESS_KEY="your-secret-key"
+export HYV_R2_ENDPOINT="https://<account-id>.r2.cloudflarestorage.com"
+export HYV_R2_BUCKET="hyv-voice-profiles"
+pip install boto3  # only dependency
+```
+
+R2 has **zero egress fees**. With ~5-20KB profiles synced once daily, annual
+cost rounds to zero. No Cloudflare Workers, no compute — just S3 PUT.
+
+Manual sync (force override):
+
+```bash
+hyv-sync \
+  --profile .hold-your-voice/voice-profile.json \
+  --force
+```
+
+### Export and import
+
+```bash
+hyv profile-export \
+  --profile .hold-your-voice/voice-profile.json \
+  --out ~/my-voice.hyv
+
+hyv profile-import \
+  --profile .hold-your-voice/voice-profile.json \
+  --source ~/my-voice.hyv
+```
+
+The learning is entirely local — no API calls, no third-party services.
+

package/assets/voice-matcher-skill.md

@@ -0,0 +1,57 @@
+---
+name: voice-matcher
+description: Use when the user wants to write from their own writing, build a voice profile from samples, match an existing writer's style, or make new copy sound like a project/person without copying generic style advice.
+---
+
+# Voice Matcher
+
+Build from the writer's own writing. Do not invent a voice from adjectives.
+
+## Source Hierarchy
+
+1. User-provided samples in the conversation.
+2. Project files the user identifies as their own writing.
+3. Obvious authored prose in the repo, such as essays, posts, emails, public
+   copy, changelog entries, or founder notes.
+4. `assets/economic-drift-voice.md` only when the user asks for Shashank's or
+   "my" voice and no better current samples exist.
+
+## Profile Build
+
+Run the portable profiler when files are available:
+
+```bash
+hyv profile \
+  --name "project voice" \
+  --out .hold-your-voice/voice-profile.json \
+  <sample paths>
+```
+
+The profile is a working benchmark, not a literary biography. It should capture:
+
+- sentence rhythm
+- paragraph shape
+- openings
+- argument pattern
+- recurring concrete textures
+- things the writer avoids
+- sample anchors that prove the profile
+
+## Writing Method
+
+- Start from the user's requested point, not from decorative tone imitation.
+- Use the profile as a constraint system.
+- Match cadence and thinking pattern before vocabulary.
+- Keep the writer's roughness when it is part of the voice.
+- Do not sand the draft into smooth, generic competence.
+- After drafting, run an AI-pattern scan and repair only weak lines.
+
+## Verification
+
+Before handing back final copy, ask:
+
+- Does the opening sound like a real observation rather than a template?
+- Could this line belong unchanged to five other people? If yes, rewrite it.
+- Are there profile anchors that justify this cadence?
+- Did the rewrite preserve the user's meaning and risk appetite?
+

package/assets/voice-profile-schema.json

@@ -0,0 +1,28 @@
+{
+  "profile_version": "hold-your-voice-portable-v1",
+  "name": "project voice",
+  "source_count": 0,
+  "word_count": 0,
+  "sentence": {
+    "avg_words": 0,
+    "variance": "medium"
+  },
+  "paragraph": {
+    "avg_sentences": 0
+  },
+  "signature": {
+    "case_style": "mixed",
+    "argument_pattern": "mixed",
+    "opening_moves": [],
+    "cadence": [],
+    "anchors": [],
+    "never_list": []
+  },
+  "voice_rules": [],
+  "ai_eliminator": {
+    "rewrite_scope": "flagged-lines-only",
+    "preserve_surrounding_lines": true,
+    "avoid_polished_founder_cadence": true
+  }
+}
+