From 627f015da8a2a68a86c700fe7f93643d12c6865a Mon Sep 17 00:00:00 2001 From: Michael Lock Date: Tue, 15 Sep 2026 08:16:35 -0700 Subject: [PATCH 1/2] Prepare v1.2.0 with voice calibration and claim-preserving edits --- .github/workflows/validate.yml | 2 + ATTRIBUTION.md | 8 +- CHANGELOG.md | 18 ++++ README.md | 46 +++++----- SKILL.md | 139 +++++++++++------------------- docs/release-1.2.0.md | 25 ++++++ docs/voice-profiles.md | 18 ++-- examples/before-after-blog.md | 126 +++++---------------------- examples/before-after-email.md | 109 +++++------------------ examples/before-after-linkedin.md | 106 +++++------------------ examples/voice-calibration.md | 34 ++++++++ install.sh | 10 ++- references/channels.md | 31 +++---- references/patterns.md | 65 ++++++++------ references/voice-calibration.md | 38 ++++++++ 15 files changed, 329 insertions(+), 446 deletions(-) create mode 100644 docs/release-1.2.0.md create mode 100644 examples/voice-calibration.md create mode 100644 references/voice-calibration.md diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 3207ec9..63c9479 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -24,11 +24,13 @@ jobs: run: | test -f references/patterns.md test -f references/channels.md + test -f references/voice-calibration.md - name: Confirm example files exist run: | test -f examples/author-voice.example.md test -f examples/brand-voice.example.md + test -f examples/voice-calibration.md test -f examples/before-after-email.md test -f examples/before-after-linkedin.md test -f examples/before-after-blog.md diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 46c34b9..82f9333 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -4,10 +4,16 @@ Humanizer's pattern catalog and detection methodology synthesize work from sever --- +## September 2026 editing enhancements + +Version 1.2 adapts Michael Lock's `sg-writing-deslop` work in [Super Green's sg-marketplace](https://github.com/Super-Green/sg-marketplace): approved voice takes precedence, facts and asks survive editing, and a final audit checks meaning as well as style. The portable calibration reference expands those ideas without requiring the marketplace plugins. + +The research credits below are inherited provenance notes. This release does not establish their numerical claims or treat the catalogue as a validated authorship test. Historical detector-evasion percentages remain only in the changelog's account of v1.1.0; active guidance makes no such claim. + ## Research and pattern sources ### Carnegie Mellon AI-writing word-frequency study (2025) -Vocabulary tier system in [`references/patterns.md`](references/patterns.md) §4 draws from CMU's frequency analysis of LLM output vs. human writing. The Tier 1 list (5–20× more common in AI than in human writing) is calibrated against that study's findings. +Vocabulary tier system in [`references/patterns.md`](references/patterns.md) §4 draws from CMU's frequency analysis of LLM output vs. human writing. The precise study and calibration have not been verified for this release; treat the word tiers as editorial defaults. ### Wikipedia "Signs of AI Writing" Several structural patterns in [`references/patterns.md`](references/patterns.md) §3 — particularly puffery, persuasive authority tropes, vague attributions, and inspirational pivots — are informed by the editor community's running catalog at [Wikipedia: WikiProject AI Cleanup / Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup/Signs_of_AI_writing). diff --git a/CHANGELOG.md b/CHANGELOG.md index 1335864..6ed28b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,24 @@ All notable changes to this project will be documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows semantic versioning. +## [1.2.0] - Unreleased + +### Added +- Evidence-based voice calibration with six observations, explicit source precedence, and a post-edit voice comparison. +- Claim-preservation checks covering attribution, uncertainty, negation, rankings, and asks. +- False-positive guidance and a worked calibration example that preserves deliberate punctuation. + +### Changed +- Existing voice guides work in their original format; profiles apply by publisher and audience, not first-person pronouns alone. +- Credibility receives a separate scan. Hollow drafts retain missing-evidence flags instead of receiving invented details. +- Structural and punctuation thresholds are editorial defaults subject to voice and purpose. Removed unsupported detector-performance claims from active skill guidance. +- Patch mode returns complete drafts under the existing output headers. Detect mode remains read-only. +- Replaced worked examples that invented customer outcomes or personal experiences with claim-preserving examples. + +### Fixed +- Installer includes examples and documentation needed for voice setup; repeated installation copies resource contents without creating nested directories. +- Setup describes a portable natural-language invocation instead of implying that this Markdown skill implements CLI flags or environment-variable discovery. + ## [1.1.0] — 2026-07-22 ### Changed diff --git a/README.md b/README.md index f23eaf0..b00d73e 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,20 @@ [![Anthropic Skills compliant](https://img.shields.io/badge/Anthropic_Skills-compliant-7E3FF2)](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) [![Status: stable](https://img.shields.io/badge/status-stable-brightgreen.svg)](CHANGELOG.md) -Humanizer is a portable writing skill — a single markdown file you can install into Claude Code, paste into Cursor, or use as a system prompt with the Anthropic, OpenAI, or any other API. It catches the structural and vocabulary patterns that make AI-generated writing read as obviously AI-generated, then rewrites the offending spans without flattening the writer's voice. +Humanizer is a portable writing skill — a Markdown entrypoint with supporting references you can install into Claude Code, paste into Cursor, or use as a system prompt with the Anthropic, OpenAI, or any other API. It catches the structural and vocabulary patterns that make AI-generated writing read as obviously AI-generated, then rewrites the offending spans without flattening the writer's voice. It's not a stylechecker. It's a final pre-delivery pass that runs before you click send. --- +## v1.2.0 release candidate + +Voice calibration now selects the publisher's guide or sample, records six evidence-based observations, and checks the edited draft against them. Existing profile formats work without conversion. An ordinary scrub needs no setup interview. + +The update also preserves claims, uncertainty, and asks; flags missing substance without inventing evidence; and packages the voice templates with the installed skill. Existing output headers stay unchanged. + +See the [changelog](CHANGELOG.md), [calibration reference](references/voice-calibration.md), and [worked calibration example](examples/voice-calibration.md). + ## Pipeline at a glance ``` @@ -30,7 +38,7 @@ It's not a stylechecker. It's a final pre-delivery pass that runs before you cli │ ┌──────────────────────────┴──────────────────────────┐ │ Step 2: Pattern scan │ - │ structural → vocab → positive → context │ + │ structure → credibility → vocab → context │ │ (16 named patterns, 3 vocab tiers, 5 punctuation │ │ budgets, banned-opener list) │ └──────────────────────────┬──────────────────────────┘ @@ -46,7 +54,7 @@ It's not a stylechecker. It's a final pre-delivery pass that runs before you cli │ ┌──────────────────────────┴──────────────────────────┐ │ Step 5: Self-audit │ - │ "What makes this still obviously AI generated?" │ + │ "Are meaning and voice preserved?" │ │ Revise again if the answer isn't "nothing." │ └──────────────────────────┬──────────────────────────┘ │ @@ -87,26 +95,20 @@ For project-scoped install (just this repo), use `./install.sh --project`. ### Cursor / Continue / Aider / other harnesses -Either paste the contents of [`SKILL.md`](SKILL.md) into your tool's rules/system-prompt file, or reference the file path. Detailed harness-specific instructions in [`docs/interoperability.md`](docs/interoperability.md). +Give the agent access to `SKILL.md` and `references/`. If the host cannot read files, include the required reference contents alongside the entrypoint. Detailed harness-specific instructions in [`docs/interoperability.md`](docs/interoperability.md). ### Raw Anthropic / OpenAI API -Use `SKILL.md` as the system prompt: +Load the entrypoint and the references into your API integration's system instructions, or provide tools that can read the references on demand. This skill does not make API calls itself. ```python -import anthropic, pathlib - -system = pathlib.Path("humanizer/SKILL.md").read_text() -draft = pathlib.Path("draft.md").read_text() - -client = anthropic.Anthropic() -msg = client.messages.create( - model="claude-opus-4-7", - max_tokens=4096, - system=system, - messages=[{"role": "user", "content": draft}], -) -print(msg.content[0].text) +from pathlib import Path + +root = Path("humanizer") +files = [root / "SKILL.md", *sorted((root / "references").glob("*.md"))] +system = "\n\n".join(path.read_text() for path in files) +draft = Path("draft.md").read_text() +# Pass system and draft to your provider's API client. ``` --- @@ -119,7 +121,7 @@ Humanizer works with zero configuration. To make it sharper for your voice or yo humanizer setup ``` -The skill walks you through a 7-question interview — your channels, sample writing, quirks to preserve, hard nos, punctuation preferences, domain vocabulary — and produces a populated voice profile file you can keep editing. +The skill walks you through an eight-question interview — your channels, sample writing, quirks to preserve, hard nos, punctuation preferences, domain vocabulary — and produces a populated voice profile file you can keep editing. You can also skip the interview and copy [`examples/author-voice.example.md`](examples/author-voice.example.md) or [`examples/brand-voice.example.md`](examples/brand-voice.example.md), then fill in the blanks. @@ -149,14 +151,14 @@ Detailed guidance in [`docs/voice-profiles.md`](docs/voice-profiles.md). ## How Humanizer differs from generic "AI humanizer" tools -Most browser-based humanizer SaaS products take AI-generated text and run it through paraphrasing models. They lower detector scores; they don't make the writing better. +Humanizer reviews finished prose inside an editing workflow. Its thresholds are editorial heuristics, not validated authorship tests or detector-score predictions. -Humanizer is the opposite shape: +The editing priorities are: - **Structural before vocabulary.** Most of the AI-tell signal is in *how* the sentences are arranged, not which words are picked. Swapping "leverage" for "use" is necessary but rarely sufficient. Humanizer scans 16 named structural patterns first. - **Voice-preserving by default.** The skill takes a voice profile (yours or your brand's) and refuses to flatten it. Short sentences, "And"/"But" starts, deliberate fragments — all preserved when the profile says so. - **Honest about hollow drafts.** A draft that passes every AI-tells check but says nothing specific gets flagged `[HOLLOW]` rather than silently approved. The model won't manufacture facts to fill the gap. -- **Self-audited.** After the rewrite, the skill asks itself *"what makes this still obviously AI generated?"* and revises again. This second pass catches more than any single sweep. +- **Self-audited.** After the rewrite, the skill asks itself whether patterns remain and meaning and voice survived and revises again. This second pass catches more than any single sweep. - **Auditable output.** You see what was flagged, what changed, and what the model thinks is still off. No black-box paraphrase. - **Not a detector-evasion tool.** Humanizer is for shipping copy you wrote with AI assistance, not laundering text past Turnitin. The framing matters: better drafts, not lower detection scores. diff --git a/SKILL.md b/SKILL.md index 101eea9..e979b9d 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: humanizer -description: Final pre-delivery scrub for AI tells on every draft. Use when the user asks to humanize a draft, scrub AI tells, run a final review or pre-publish check, de-robot text, audit AI-likeness, or prepare any draft (email, Slack, LinkedIn, blog, case study, landing page, newsletter, sales collateral, meeting agenda, feedback note) before sending or publishing. First-run onboarding via "humanizer setup" or "configure humanizer". Returns a corrected draft plus a structured report of issues found. +description: Scrub AI writing patterns from finished drafts while preserving voice and facts. Use to humanize, de-robot, rewrite, or audit text before publishing. Supports author samples, brand guides, and optional voice-profile setup; returns edits and a structured report. --- # Humanizer @@ -9,13 +9,19 @@ Final pre-delivery scrub for AI tells. Run on every draft longer than a single s A draft can use zero banned words and still read like a robot if it leans on dramatic reframes, staccato rhythm, and manufactured punchlines, which is why the scan runs structural before vocab before positive checks before context. -**A draft is read by two kinds of reader, and they weigh different things.** A person notices reframes, punchlines, and buzzwords — the tells this skill has always caught. A statistical detector (Pangram-class, now running on Substack, LinkedIn, and academic tools) barely reads vocabulary; it scores **structural regularity** — uniform sentence length, evenly-shaped paragraphs, formulaic transitions, and the over-smoothed cadence a polishing pass leaves behind. Both readers are always in play, so every pass addresses structure and vocab together — and runs structure first, because it is the higher-signal axis and the one this skill historically under-weighted (in one test, structural rewriting evaded detection ~89% of the time versus ~34% for synonym-swapping). The trap is polishing toward uniformity: smoothing cadence flat lowers human-perceived tells while *raising* a detector's score. Increase variance; never even it out. The cadence check lives in `references/patterns.md` §3.3. +Structure comes first because reshaping a paragraph changes which words survive. Check repeated reframes, manufactured punchlines, uniform cadence, and same-shaped paragraphs before swapping vocabulary. These are editorial heuristics, not proof of authorship or a prediction of any detector's score. + +## Preserve meaning before style + +A tell is a pattern, not an isolated word or punctuation mark. Approved voice guidance and deliberate choices outrank this catalogue. Preserve factual claims, attribution, uncertainty, negation, comparisons, rankings, and the author's intended asks. Never add an ask, deadline, personal experience, number, or opinion to make a draft sound more human. + +Keep code, commands, identifiers, product names, legal text, quotations, and terminology under discussion verbatim. A suspected factual problem belongs in the report: an unsourced claim is not necessarily false. Correct or remove a claim only when supplied evidence or the user's instruction supports the change, and disclose it. Otherwise preserve it and flag verification; do not present the draft as ready to publish. Severity maps to action: | Severity | Meaning | Action | |---|---|---| -| **CRITICAL (P0)** | Credibility killer. Reader loses trust. | Always fix. No exceptions. | +| **CRITICAL (P0)** | Credibility killer. Reader loses trust. | Resolve explicitly; preserve and report unresolved claims. | | **HIGH (P1)** | Clear AI tell. Reader notices. | Fix unless the pattern is intentional and earned. | | **MEDIUM (P2)** | Stylistic drag. Accumulates. | Fix if 2+ in same piece, or if combined with other patterns. | | **LOW** | Watch-list. Only flag in clusters. | Note if density is high; otherwise leave. | @@ -44,12 +50,12 @@ Without either profile, the skill preserves the draft's existing voice and appli ## Workflow -Six-step pipeline: +Workflow: ``` 0. Auto-detect channel + voice target 1. Voice calibration (conditional) -2. Pattern scan (structural → vocab → positive → context) +2. Pattern scan (structural → credibility → vocab → positive → context) 3. Severity gate (patch vs. full rewrite; clean-but-hollow check) 4. Rewrite at chosen depth 5. Self-audit (mandatory long-form; conditional short-form) @@ -60,18 +66,15 @@ Six-step pipeline: Infer channel silently from cues (greeting/salutation, file path, word count, hashtags, code fences, voice cues). See `references/channels.md` → Auto-Detect Cues. Default to `generic long-form` if ambiguous and note the assumption in the final report. Don't ask unless two or more channels are genuinely plausible. -### Step 1 — Voice calibration (conditional) +### Step 1 — Voice calibration -Skip by default. Run only when one of these is true: +Resolve the voice before scanning. Use the user's instructions for this draft first, then the approved guide or sample for whoever will publish it, then applicable upstream voice instructions, and finally the draft's existing voice. A personal profile does not govern a brand asset just because that person wrote it. Within the selected voice, explicit preferences outrank inferred habits. Ask only when conflicting sources would materially change the edit. -1. The user pastes a writing sample and asks for voice-matched output. -2. An author voice profile is configured and the draft is first-person / personal. -3. A brand voice profile is configured and the draft is client-facing or organizational. -4. The draft was produced by an upstream drafting agent with its own voice rules; the humanizer runs as a final pass and respects its register. +Read `references/voice-calibration.md` when a sample or profile is supplied, the user requests voice matching, or upstream voice rules apply. Capture six observations: sentence rhythm, word choice, paragraph openings, punctuation, recurring phrasing, and transitions. Cite short sample spans or guide sections; mark weak evidence instead of inventing precise rates from a tiny sample. -When calibrating from a sample, capture a six-line voice profile: sentence-length distribution, word-choice level, paragraph openers, punctuation habits, recurring phrases, transition style. Keep in working memory for Steps 4 and 5. +Apply this to writing as a person even when it contains no first-person pronouns. Use a supplied profile in its existing format; do not require conversion to Humanizer's template. If a requested source cannot be read, say so. For an ordinary scrub, continue conservatively in the draft's voice; for an explicit voice match, request the missing source before claiming a match. -Never fabricate a voice profile. If no trigger fires, preserve the draft's existing voice rather than imposing one. +Calibration is transient. Do not save a profile or change configuration unless the user asks. With no source, skip profiling and preserve what is there. ### Step 2 — Pattern scan @@ -79,9 +82,10 @@ Fixed order — structural tells are load-bearing; vocab tells are surface. **Re 1. **Dramatic reframe + punchline structures** (patterns §3.1, §3.2) — the highest-signal tells 2. **Structural patterns** (§3.3 through §3.16) -3. **Vocabulary tiers** (§4) -4. **Positive checks** — is there a point of view, a concrete detail, an earned opener? -5. **Context checks** — punctuation budgets (§6), banned openers (§7), register-appropriate forms +3. **Credibility** (§2): flag unsupported attribution and preserve real uncertainty; never substitute invented evidence. +4. **Vocabulary tiers** (§4) +5. **Positive checks** — is there a point of view, a concrete detail, an earned opener? +6. **Context checks** — punctuation budgets (§6), banned openers (§7), register-appropriate forms Tally hits. Group vocab hits by category — category count feeds Step 3. @@ -92,9 +96,9 @@ Tally hits. Group vocab hits by category — category count feeds Step 3. - 3+ distinct pattern categories triggered - Uniform sentence length — three-plus consecutive sentences within 2 words of each other -**Structure can trigger a rewrite on its own.** If cadence and paragraph shape are uniform across the piece (`references/patterns.md` §3.3) — the dominant signal for a statistical detector — go to full rewrite even when the vocab is clean and no other category fired. Patching smooths the surface; it does not add the structural variance a uniform draft is missing. +**Structure can trigger a rewrite on its own.** If cadence and paragraph shape are uniform across the piece (`references/patterns.md` §3.3) and the repetition weakens the reading experience, go to full rewrite even when the vocab is clean and no other category fired. Patching smooths the surface; it does not add the structural variance a uniform draft is missing. -Otherwise patch mode. Surgical edits only, leave the rest alone. +Otherwise patch mode. Surgical edits only, leave the rest alone. Numeric thresholds are review cues, not mechanical commands: short messages, procedures, deliberate parallelism, and approved voice can justify regular rhythm. **Clean-but-hollow flag.** If the draft passes the scan but says nothing — no concrete claim, no specific example, no defensible point of view — flag `[HOLLOW]` explicitly. A clean-style draft with no substance is still broken. @@ -102,9 +106,9 @@ Otherwise patch mode. Surgical edits only, leave the rest alone. Produce the rewrite at the depth Step 3 chose. Preserve the writer's voice and argument. The humanizer removes tells; it does not impose a house style on a draft that already has one. -Fix structure before vocabulary. Re-shaping sentence lengths and paragraph blocks does more than swapping words — for a human reader it kills the robotic cadence, and for a detector it is nearly the whole game (word-level edits barely move a classifier). Where the draft is generic, add specific voice: a real detail, a named example, a stated opinion. Do not flatten the result into even cadence on the way out. +Fix structure before vocabulary. First give each sentence room for its job: a claim may need detail; a pivot may be short. Then cut filler within that shape. Never pad to meet a word-count target or flatten every sentence to the same length. Preserve useful details and mixed feelings already present; add specificity only from supplied evidence, with its attribution intact. -For **patch mode**, show only edited spans with minimal surrounding context. For **full rewrite**, produce the full replacement. +In patch mode, change only affected spans, but return the complete corrected draft under both output headers. In full mode, rebuild structure while preserving meaning. If substance is missing, report the gap; editing cannot supply the author's experience or evidence. ### Step 5 — Self-audit (mandatory second pass) @@ -114,15 +118,13 @@ The load-bearing step of the pipeline. Do not skip on long-form. **Conditional for:** Slack messages, short internal emails, CTAs, subject lines — skip **only if** Step 2 flagged nothing. -Two prompts, asked internally, answered in writing: - -> **Prompt 1:** "What makes the below so obviously AI generated?" -> List every residual tell in the rewritten draft — vocabulary *and* structure. Read part of it as a statistical detector would: name any uniform sentence-length band, same-shape paragraph runs, formulaic transitions, over-hedged neutral tone, or over-smoothed polish, since that is what the machine weights most heavily. Do not protect your own work. If none, say "None" with a one-sentence justification. +Audit the candidate and report concise findings: -> **Prompt 2:** "Now make it not obviously AI generated." -> Revise against every tell surfaced in Prompt 1. Favor restructuring sentences and paragraphs over swapping words — word-level edits barely move a detector, and structure is where both readers are looking. +1. What residual patterns weaken this draft? Inspect structure as well as vocabulary, without assuming the text must contain a tell. +2. Did any fact, name, number, date, quotation, citation, ranking, qualification, negation, or ask change? Restore accidental changes. Report any evidence-backed correction separately. +3. Does the edit still match the selected voice, including its deliberate exceptions? Restore voice flattened by generic rules. -If Prompt 1 returns "None" and the justification holds, skip Prompt 2 and emit. +Revise against those findings. If nothing remains, say so with a brief reason. When a short clean draft skips the audit, say "Skipped: short draft with no findings" under Self-Audit. This is an editorial check, not an authorship verdict. ### Step 6 — Emit final + report @@ -156,7 +158,7 @@ Two modes. Default to **Rewrite**. Use **Detect** when the user says "scan," "ch ## Self-Audit -"What makes the above so obviously AI generated?" +"What patterns remain, and were meaning and voice preserved?" - - @@ -196,11 +198,11 @@ When the draft has no CRITICAL/HIGH issues but no concrete claims, numbers, name `- **[HOLLOW]** Passes AI scan but lacks substance: .` -In Rewrite mode, the Final Version must add substance, not just polish. Never silently approve a hollow draft. See `references/channels.md` → Per-Channel Hollow Failure Modes for what counts as hollow per channel. +In Rewrite mode, preserve the supported content in Final Version and mark the missing substance in the report. Do not invent it or insert a publishable-looking placeholder. State that the draft needs author input before publication. See `references/channels.md` → Per-Channel Hollow Failure Modes for what counts as hollow per channel. ### Nothing Flagged -If the draft is clean: `## Issues Found` = `- None detected.`, Rewritten Draft = original, Self-Audit still runs, Final Version emitted verbatim. **Emit all section headers even on a clean pass** — downstream agents parse by header. Detect mode is the one exception; it does not emit `## Final Version`. +If the draft is clean: `## Issues Found` = `- None detected.`, Rewritten Draft = original, Self-Audit follows Step 5, Final Version emitted verbatim. **Emit all section headers even on a clean pass** — downstream agents parse by header. Detect mode is the one exception; it does not emit `## Final Version`. ### Setup Mode @@ -234,7 +236,7 @@ Q5. Hard nos. beyond the universal Tier 1 list, idioms that don't fit your audience. Q6. Punctuation preferences. - a) Em dashes: allowed (default), reduced (max 1 / 500 words), or banned? + a) Em dashes: unrestricted, reduced (default: max 1 / 500 words), or banned? b) Exclamation points: default, casual channels only, or never? c) Anything else? (e.g., Oxford comma always, no semicolons.) @@ -252,15 +254,15 @@ Q8. Where should the profile be saved? ``` Voice profile saved to . -To use it: - • Pass --voice when invoking, OR - • Set HUMANIZER_AUTHOR_VOICE=, OR - • Reference it in your project's agent config so the skill auto-loads it. +To use it, tell your agent: + Humanize this draft using the voice profile at . -To edit later: open the file directly. To re-run: "humanizer setup --replace". +To edit later, open the file or ask to update the profile. ``` -**Re-running setup.** If the profile already exists, default to `--update` (additive — only ask questions whose answers can't be inferred). User must pass `--replace` to start over. +Humanizer is a Markdown skill, not a CLI. Flags and environment variables only work if the host integration explicitly implements them. Use a path or pasted profile as the portable interface. + +**Re-running setup.** If the profile already exists, update only the requested sections. Ask for missing information instead of inventing it. Replace the whole profile only when the user explicitly requests replacement. **Brand profile after author profile.** When Q1 = "Both", run the same interview a second time with brand framing. @@ -268,64 +270,19 @@ To edit later: open the file directly. To re-run: "humanizer setup --replace". --- -## Worked Mini-Example - -**Input (Slack draft):** "Quick update — we're leveraging the new workflow to streamline onboarding and it's been transformative for the team." - -**Output:** +## Worked mini-example -``` -## Issues Found +Input: "We're leveraging the new workflow to streamline onboarding. It's been transformative for the team." -- **[CRITICAL]** "leveraging" — Tier 1 vocab → "using" -- **[CRITICAL]** "streamline" — Tier 1 vocab → "speed up" or cut -- **[CRITICAL]** "transformative" — Tier 1 vocab → replace with a concrete result -- **[HOLLOW]** Passes scan but no specifics: which workflow? how much faster? - -## Rewritten Draft - -Quick update: the new onboarding workflow is saving us about a day per new hire. - -## What Changed +Edit: "We're using the new workflow to make onboarding faster. It's made a big difference to the team." -- Swapped three Tier 1 words for plain verbs -- Added concrete result (day per hire) to replace vague praise -- Replaced em dash with colon (cleaner for short Slack message) +Report: The edit keeps the author's qualitative claims, without verifying them. `[HOLLOW]`: the workflow and the result are unspecified; ask the author for an example before publication. Do not replace "transformative" with an invented day saved per hire. -## Self-Audit - -"What makes the above so obviously AI generated?" - -- None detected. "Quick update:" reads natural for Slack. - -## Final Version - -Quick update: the new onboarding workflow is saving us about a day per new hire. - -## Humanizer Report - -- Channel detected: slack -- Voice loaded: none -- Rewrite depth: patch -- Clean-but-hollow: no (added specifics) -- Notes: em dash → colon -``` - -For longer worked examples (email, LinkedIn, blog), see `examples/before-after-*.md`. - ---- +See `examples/before-after-*.md` for complete examples and `examples/voice-calibration.md` for sample-based calibration. ## Sources -Detection patterns synthesized from: -- Carnegie Mellon (2025) AI-writing word-frequency study -- Wikipedia "Signs of AI Writing" editor guidance -- Buffer 52M-post LinkedIn analysis (2025) -- blader/ai-detection open-source taxonomy -- conor-humanizer 3-tier vocabulary model -- jalaalrd/ai-writing-tells quantified budgets -- "The Humanizer" LinkedIn archetype catalog -- Pangram/classifier false-positive research (2026): structure — sentence-length variance and paragraph shape — is the dominant statistical-detector signal (structural rewriting ~89% vs. synonym-swap ~34% evasion in one 10M-word test); over-polishing and commercial humanizer tools *increase* detectability over time; encoding tricks (zero-width chars, homoglyphs) are normalized out before scoring +The inherited pattern catalogue and its historical attributions are documented in `ATTRIBUTION.md`. The voice-precedence and claim-preservation additions adapt Michael Lock's September 2026 deslop work. Thresholds are editorial defaults, not validated detection rates. No detector-evasion benchmark is claimed. --- @@ -344,9 +301,9 @@ Sometimes a flagged pattern is the right call — a tricolon that's actually ear - **Don't strip voice to hit the checklist.** Short sentences, fragments, and "And"/"But" starts can be intentional. The humanizer removes tells; it does not normalize every piece into beige corporate prose. - **Don't add words for the sake of it.** If a sentence is tight and clear, don't lengthen it to avoid "staccato." The staccato tell is about uniformity across the whole piece, not individual short sentences. -- **Don't polish toward uniformity.** Smoothing cadence flat, equalizing paragraph shapes, and hedging every claim to neutral reduces *human*-perceived tells while *raising* a statistical detector's score — the two readers pull opposite ways here. Preserve or increase structural variance and keep the small imperfections; a perfectly even draft is a machine signature. -- **Don't reach for gimmicks.** Zero-width characters, homoglyphs, unicode swaps, forced typos, and commercial "humanizer" tools do not survive a detector — text is normalized before scoring, and a tool's consistent rewrite signature becomes a *new* pattern detectors retrain on. The only durable fix is genuine structural variance and specific voice; if a draft is fully machine-generated, the honest answer is to actually write it. -- **Don't fabricate replacements.** If you're cutting a vague authority claim ("studies show..."), don't invent a source. Cut the claim or flag it with `[ADD SPECIFIC SOURCE OR CUT]` inline. +- **Don't polish toward uniformity.** Preserve natural variation where it serves meaning. Deliberate repetition and consistent procedure steps can be useful. +- **Don't reach for gimmicks.** Forced typos, invisible characters, or arbitrary punctuation do not improve the writing. Do not promise detector evasion. +- **Don't fabricate replacements.** Flag an unsupported claim for verification; never manufacture evidence, silently delete information, or turn uncertainty into certainty. - **Don't rewrite past the user's intent.** If the piece is meant to be punchy (ad headline, stop-scroll caption, subject line), the structural rules loosen. Judgment over mechanical application. - **Don't silently approve a hollow draft.** A draft that passes every tell but says nothing specific is still broken. Flag `[HOLLOW]` and let the user decide. - **Don't decline the task; escalate instead.** If a full rewrite would require replacing >80% of the words, the draft is a ghost-write request, not a humanizing task. Return it with a note rather than fabricating new content. diff --git a/docs/release-1.2.0.md b/docs/release-1.2.0.md new file mode 100644 index 0000000..0feaf28 --- /dev/null +++ b/docs/release-1.2.0.md @@ -0,0 +1,25 @@ +# v1.2.0 release preparation + +Status: release candidate, not tagged or published. The changelog is intentionally Unreleased. + +## Scope + +Calibrate from the intended publisher's voice source, preserve claims and asks, and report missing substance without inventing it. Keep existing output headers and the default rewrite/detect behavior. Install the resources referenced by setup. + +## Validation + +- Repository validator: passed, 261-character description and 305-line body. +- Shell syntax and git whitespace checks: passed. +- Fresh and repeated installation into a temporary target: passed. Reference, example, and documentation contents matched the source; no nested resource directories appeared. +- Local Markdown links: checked for existing targets. +- Independent read-only review: corrected conflicting qualifier, pronoun, setup, and authorship guidance. Existing output headers were confirmed unchanged. +- One forward exercise preserved a date, number, uncertainty, request, technical term, code, and explicit punctuation preferences without editing them. +- Two qualitative baseline/current simulations covered a hollow update and competing brand/personal profiles. Both versions could return safe output; the new version removes contradictory instructions. These are reviewer exercises, not controlled model benchmarks or evidence of a measured quality gain. + +## Release steps + +1. Review and merge the release pull request after CI passes. +2. Replace Unreleased with the actual release date and remove the README's release-candidate label. +3. Tag the reviewed commit as v1.2.0 and publish release notes based on CHANGELOG.md. + +No tag or published release is part of this preparation. diff --git a/docs/voice-profiles.md b/docs/voice-profiles.md index 597057a..093c127 100644 --- a/docs/voice-profiles.md +++ b/docs/voice-profiles.md @@ -18,7 +18,7 @@ There are two flavors: - **Author voice profile** — first-person writing. Emails, Slack, LinkedIn (personal), internal memos, feedback notes. - **Brand voice profile** — organizational/client-facing writing. Blog, case studies, landing pages, marketing emails, LinkedIn (org). -You can have one, both, or neither. The skill picks the right one based on channel. +You can have one, both, or neither. The skill selects the publisher's voice using the request and audience, not pronouns alone. Explicit instructions outrank inferred sample habits. Existing profile formats work without conversion. Templates: [`examples/author-voice.example.md`](../examples/author-voice.example.md), [`examples/brand-voice.example.md`](../examples/brand-voice.example.md). @@ -30,7 +30,7 @@ Voice profile content varies in usefulness. Some sections do real work; others a ### High-leverage (these change the rewrite) -- **Sample paragraphs** of your real writing. Three short ones is plenty. The skill reads register, sentence-length distribution, paragraph openers, and punctuation habits from these — not from your self-description, which is rarely accurate. **If you only fill in one section, fill in this one.** +- **Sample paragraphs** of your real writing. Three short ones is plenty. The skill reads register, sentence-length distribution, paragraph openers, and punctuation habits from these — while explicit instructions establish your preferred style. **If you only fill in one section, fill in this one.** - **Hard nos.** Phrases or tropes you never want. The skill treats these as additions to the universal banned list (§7). Be specific — "never use 'in today's [anything]'" is operational; "be authentic" isn't. - **Quirks to preserve.** Patterns the skill should not flag. The defaults in §8 cover common ones (sentence fragments, "And"/"But" starts, one-line paragraphs in casual channels). List anything additional that's specific to you. - **Punctuation preferences.** Em dash defaults to "max 1 per 500 words"; if you ban them entirely, say so. @@ -44,7 +44,7 @@ Voice profile content varies in usefulness. Some sections do real work; others a ### Low-leverage (skip unless you really care) -- **Self-description of your "register"** ("warm and conversational"). Almost never matches the samples. The skill calibrates from the samples; the description gets ignored. +- **Self-description of your "register"** ("warm and conversational"). Too broad to resolve many line-level choices without examples. Use samples as evidence of habits, while honoring explicit instructions about the desired register. - **Lists of writers/brands you admire.** Doesn't translate to detectable patterns. - **Mood adjectives** ("approachable yet authoritative"). Decorative. @@ -64,14 +64,14 @@ Three short real samples beat one long fabricated one. - Things you wish you wrote that way — the skill needs the actual baseline - AI-generated text you "made sound like you" — defeats the purpose -If you don't have anything written down, paste a transcript of yourself talking about a work topic for 60 seconds. Spoken register is closer to natural writing than carefully edited prose for most people. +If you don't have anything written down, paste a transcript of yourself talking about a work topic for 60 seconds. Label it as spoken language; its rhythm may not transfer to written prose. --- ## When NOT to load a voice profile -- **Anonymous register** (Reddit replies, anonymous forums). Loading a profile would make the writing recognizable as you. -- **Pure technical/regulatory content.** Voice doesn't matter; correctness does. +- **Anonymous register** (Reddit replies, anonymous forums). Use only a profile appropriate to the requested anonymous register. +- **Technical/regulatory content.** Preserve code, legal text, and precise terms. Apply a relevant voice guide only to surrounding prose. - **One-shot drafts in someone else's voice** (writing as a colleague, ghostwriting). Use a one-time sample paste instead — Step 1 in the skill walks through this. --- @@ -102,7 +102,7 @@ Profiles aren't static. If the skill flags the same pattern three times across d That's the cue to update §8 (author carve-outs) of your profile so the skill stops flagging it. Same for words that should be exempt from Tier 2/3 density checks — add them to the "domain vocabulary" section. -If your role/audience changes substantially, run `humanizer setup --replace` and re-do the interview from scratch. +If your role/audience changes substantially, ask Humanizer to replace the profile using new samples and preferences. --- @@ -110,3 +110,7 @@ If your role/audience changes substantially, run `humanizer setup --replace` and - [Author voice profile template](../examples/author-voice.example.md) - [Brand voice profile template](../examples/brand-voice.example.md) + +## Calibration in v1.2 + +Use `Humanize this draft using the voice profile at ` or paste a sample. The six-dimension calibration and post-edit comparison live in [references/voice-calibration.md](../references/voice-calibration.md). Calibration stays within the current task unless you request a saved profile. Missing samples yield stated preferences, not fabricated measurements. diff --git a/examples/before-after-blog.md b/examples/before-after-blog.md index ae2c0e9..b4816d3 100644 --- a/examples/before-after-blog.md +++ b/examples/before-after-blog.md @@ -1,123 +1,37 @@ -# Worked Example — Blog Intro +# Worked example: Blog introduction with missing evidence -The opening 200 words of a generic AI-generated B2B blog post. Walked through Humanizer with a brand voice profile loaded. - ---- +This is a synthetic editing fixture. Facts inside the draft are user-supplied for the exercise, not real-world evidence. No additional source or voice profile is available. ## Input draft +```text +Customer onboarding is about helping people use the product and reach their goals. Studies show that 73% of customers leave within 90 days because of poor onboarding. Let's dive in. ``` -# Why Customer Onboarding Is the Hidden Lever for SaaS Growth - -In today's competitive SaaS landscape, customer onboarding has emerged as a -pivotal differentiator. Yet most companies still treat it as an afterthought. - -Studies show that 73% of SaaS customers churn within the first 90 days due -to poor onboarding experiences. The cost? Billions in lost revenue annually. - -But here's the thing: onboarding isn't just about teaching customers how to -use your product. It's about empowering them to achieve their goals, -fostering long-term relationships, and unlocking the full value of your -solution. - -The best SaaS companies understand this. They've moved beyond simple -walkthroughs and embraced a more holistic approach — one that combines -personalized guidance, proactive support, and continuous engagement. - -In this article, we'll explore the strategies that separate world-class -onboarding programs from the rest. You'll learn how to build a scalable -onboarding framework, leverage data to drive better outcomes, and -ultimately transform your onboarding from a cost center into a growth -engine. - -Let's dive in. -``` - ---- - -## Pipeline output - -### Step 0 — Channel detected - -Blog post (H1, >200 words, "we" + "you" voice mixing). - -### Step 1 — Voice calibration - -Brand profile loaded. Strict mode (blog/case-study). One-line paragraphs and staccato are flagged here. - -### Step 2 — Pattern scan - -**Issues Found** - -- **[HIGH]** "In today's competitive SaaS landscape" — Banned opener (§7) → cut -- **[CRITICAL]** "pivotal" — Tier 1 vocab → "common" or specific -- **[CRITICAL]** "Studies show that 73% of SaaS customers..." — Universal authority without source (§3.14) + likely fabricated stat (§2). If real, cite the study; if not, cut -- **[HIGH]** "The cost? Billions in lost revenue annually." — Dramatic fragment Q&A (§3.5) -- **[HIGH]** "But here's the thing:" — Inspirational pivot (§3.11) + performative directness (§3.4) -- **[HIGH]** "It's not just X. It's Y. It's Z. It's W." — Dramatic reframe (§3.1) + tricolon stack -- **[CRITICAL]** "empowering" — Tier 1 vocab -- **[CRITICAL]** "fostering" — Tier 2 vocab + cluster -- **[CRITICAL]** "unlocking" — Tier 1 vocab -- **[CRITICAL]** "holistic" — Tier 2 vocab -- **[HIGH]** "personalized guidance, proactive support, and continuous engagement" — Compulsive tricolon (§5) -- **[CRITICAL]** "world-class" — Tier 3 cliché (auto-cut in brand-voice strict mode) -- **[HIGH]** "scalable onboarding framework, leverage data, transform your onboarding" — Tier 1 cluster + present participle stacking -- **[CRITICAL]** "transform [...] into a growth engine" — Tier 1 vocab + bumper-sticker phrase -- **[HIGH]** "Let's dive in." — Manufactured closer / chatbot artifact-adjacent - -### Step 3 — Severity gate - -10+ Tier 1/2 hits, 5+ pattern categories, several uniform-length sentences. **Full rewrite.** - -### Step 4 — Rewrite - -``` -# Why Customer Onboarding Is the Hidden Lever for SaaS Growth - -We worked with a team that lost 40% of new customers in the first 90 days. -The product was strong. The sales motion was efficient. The onboarding was -a 12-step email sequence that no one read. -When they replaced the sequence with a single 25-minute kickoff call — -delivered by a customer success manager, not a bot — the 90-day retention -rate moved from 60% to 88% in two quarters. Nothing else changed. - -That isn't an unusual result. The teams we've watched build durable revenue -treat onboarding as a deliberate, supported handoff between sales and the -product. The teams that struggle treat it as a sequence of automated -emails. The gap between those two approaches is where most early-stage -churn lives. - -This piece walks through what we've seen work. It's specific to SaaS -companies under 200 employees, where the customer success team is small -enough that one person's process becomes the company's process. If that's -you, the next section is the most important one. -``` +## Issues Found -### Step 5 — Self-audit +- [CRITICAL] "Studies show" has no supplied source; verify the figure and causal attribution. "Let's dive in" adds no information. -> "What makes the above so obviously AI generated?" +## Rewritten Draft -- "That isn't an unusual result" is faintly templated. Acceptable in long-form blog opening; leave. -- "The teams that build / the teams that struggle" is parallel — borderline anaphora, but only two beats and not stacked, so it's rhythm rather than tell. -- "If that's you, the next section..." is a soft engagement hook but does real work (it tells under-200-employee SaaS readers they're the audience). Earned. +Customer onboarding helps people use the product and reach their goals. Studies show that 73% of customers leave within 90 days because of poor onboarding. -No revision needed. +## What Changed -### Final Version +- Removed or replaced the flagged phrasing while retaining the substantive claims and intent. -(same as above) +## Self-Audit -### Humanizer Report +Names, numbers, qualifications, and asks match the input. No anecdote or outcome was added. The existing register remains; no voice match is claimed. -- **Channel detected:** blog (brand voice strict) -- **Voice loaded:** brand profile -- **Rewrite depth:** full -- **Clean-but-hollow:** no (specific scenario, specific number, specific audience cut) -- **Notes:** killed the "73% / billions" fabricated stat; replaced banned opener with a real story; cut 7 Tier 1/2 vocab hits; rewrote the inspirational-pivot opener with a concrete result; preserved varied sentence lengths +## Final Version ---- +Customer onboarding helps people use the product and reach their goals. Studies show that 73% of customers leave within 90 days because of poor onboarding. -## What this example shows +## Humanizer Report -Most generic SaaS blog intros stack 4–6 high-severity patterns in a single 200-word block. Patching word-by-word would still leave the structure AI-shaped. Full rewrite from a real anchor (specific company, specific number, specific result) is the only fix that holds up. +- Channel detected: blog +- Voice loaded: none +- Rewrite depth: patch +- Clean-but-hollow: yes; supporting evidence is missing +- Notes: Unresolved: the statistic and its source need verification before publication. Preserve the claim while flagging it; do not invent a replacement case study or silently discard the figure. diff --git a/examples/before-after-email.md b/examples/before-after-email.md index 738b9c0..aaa22b8 100644 --- a/examples/before-after-email.md +++ b/examples/before-after-email.md @@ -1,117 +1,52 @@ -# Worked Example — Sales Email +# Worked example: Sales email -A short cold-outreach email that triggers four AI tells. Walked through the full Humanizer pipeline. - ---- +This is a synthetic editing fixture. Facts inside the draft are user-supplied for the exercise, not real-world evidence. No additional source or voice profile is available. ## Input draft -``` -Subject: A quick thought on your onboarding workflow - +```text Hi Sarah, -I hope this email finds you well! I noticed your team has been growing rapidly, -and I wanted to share a quick thought. - -In today's competitive landscape, leveraging the right onboarding workflow -isn't just important — it's transformative. We've helped dozens of companies -streamline their processes, unlock better retention, and empower their teams -to focus on what really matters. - -I'd love to learn more about your specific challenges and explore how we -might help. Would you be open to a brief 15-minute call next week? - -Let me know if you'd like me to share some additional materials in the -meantime! +We have helped dozens of companies streamline onboarding and improve retention. Would you be open to a 15-minute call next week? I can also send materials. Best, Alex ``` ---- - -## Pipeline output - -### Step 0 — Channel detected - -Email (greeting + sign-off + 1:1 register). - -### Step 1 — Voice calibration - -No voice profile loaded. Preserving draft's existing register; flagging tells universal to AI-generated outreach. - -### Step 2 — Pattern scan - -**Issues Found** +## Issues Found -- **[CRITICAL]** "I hope this email finds you well!" — Sycophancy / opening throat-clearing → cut -- **[CRITICAL]** "Let me know if you'd like me to share some additional materials in the meantime!" — Chatbot artifact + unearned exclamation → cut -- **[HIGH]** "In today's competitive landscape" — Banned opener (§7) → cut -- **[HIGH]** "isn't just important — it's transformative" — Dramatic reframe (§3.1) + Tier 1 vocab ("transformative") -- **[CRITICAL]** "leveraging" — Tier 1 vocab → "using" or specific verb -- **[CRITICAL]** "streamline" — Tier 1 vocab → "speed up" or specific outcome -- **[CRITICAL]** "unlock" — Tier 1 vocab → cut or replace with specific outcome -- **[CRITICAL]** "empower their teams" — Tier 1 vocab + vague claim -- **[HIGH]** "Helped dozens of companies streamline / unlock / empower" — Present participle stacking (§5) -- **[HIGH]** "what really matters" — Filler qualifier ("really") + meaningless phrase -- **[HOLLOW]** No specific reason for outreach, no specific result, no specific stake. Reads like a template. +- [HIGH] "streamline" is generic vocabulary; replace it with a plain description. -### Step 3 — Severity gate - -Six Tier 1 hits, four pattern categories, plus `[HOLLOW]` → **full rewrite**. - -### Step 4 — Rewrite - -``` -Subject: Onboarding times at [Company] +## Rewritten Draft Hi Sarah, -We worked with three SaaS teams in the last quarter that were growing the way -yours is, and the same pattern showed up: onboarding time per hire crept from -three days to six as the team passed thirty people. Each had a different fix. +We have helped dozens of companies make onboarding faster and improve retention. Would you be open to a 15-minute call next week? I can also send materials. -If that pattern is on your radar at all, I'd be glad to share what worked for -the team that recovered the fastest — fifteen minutes, no slides. - -Thanks, +Best, Alex -``` -### Step 5 — Self-audit +## What Changed -> "What makes the above so obviously AI generated?" +- Removed or replaced the flagged phrasing while retaining the substantive claims and intent. -- "If that pattern is on your radar" reads slightly templated. Tighter: "If you're seeing this..." -- The fifteen-minutes-no-slides sign-off is fine for cold email but borderline cliché. Leave for now; flag if it shows up again. +## Self-Audit -Revision pass: +Names, numbers, qualifications, and asks match the input. No anecdote or outcome was added. The existing register remains; no voice match is claimed. -``` -Subject: Onboarding times at [Company] +## Final Version Hi Sarah, -We worked with three SaaS teams in the last quarter that were growing the way -yours is, and the same pattern showed up: onboarding time per hire crept from -three days to six as the team passed thirty people. Each had a different fix. - -If you're seeing this, I'd be glad to share what worked for the team that -recovered the fastest. Fifteen minutes, no slides. +We have helped dozens of companies make onboarding faster and improve retention. Would you be open to a 15-minute call next week? I can also send materials. -Thanks, +Best, Alex -``` - -### Final Version - -(same as above) -### Humanizer Report +## Humanizer Report -- **Channel detected:** email -- **Voice loaded:** none -- **Rewrite depth:** full -- **Clean-but-hollow:** no (specific situation, specific stake, specific ask) -- **Notes:** swapped 6 Tier 1 words; cut sycophancy + chatbot artifact + banned opener; replaced participle stack with named result; added a real-world reason for outreach +- Channel detected: email +- Voice loaded: none +- Rewrite depth: patch +- Clean-but-hollow: no; the point is understandable, though supporting examples could strengthen it +- Notes: The qualitative result and "dozens" are supplied claims, not independently verified. A named example would strengthen the pitch. Preserve the meeting duration, next-week timing, and offer to send materials. diff --git a/examples/before-after-linkedin.md b/examples/before-after-linkedin.md index 90699fc..c18307f 100644 --- a/examples/before-after-linkedin.md +++ b/examples/before-after-linkedin.md @@ -1,103 +1,37 @@ -# Worked Example — LinkedIn Post (Personal) +# Worked example: Personal LinkedIn post -A 180-word personal LinkedIn post written in a generic AI shape. Walked through Humanizer with a personal voice profile loaded. - ---- +This is a synthetic editing fixture. Facts inside the draft are user-supplied for the exercise, not real-world evidence. No additional source or voice profile is available. ## Input draft +```text +Here's the truth: the best leaders I've worked with hire slowly. They define the role, the bar, and the trade-offs before choosing someone. It's not magic. It's discipline. ``` -Most leaders think hiring is a numbers problem. - -It isn't. - -Hiring is a clarity problem. When you don't know what good looks like, you -hire mediocrity. When you don't know what the role actually does, you hire -mismatch. When you don't know who's accountable, you hire chaos. - -Here's the truth: the best leaders I've worked with don't hire faster. -They hire slower — and with more conviction. - -They define the role. They define the bar. They define the trade-offs. - -And then they say no, again and again, until the right person walks in. - -It's not magic. It's discipline. - -What's something you've learned about hiring that took you too long -to figure out? -``` - ---- - -## Pipeline output - -### Step 0 — Channel detected - -LinkedIn — personal (first-person, anecdotal frame, conversational length). - -### Step 1 — Voice calibration - -Author profile loaded. Profile preserves: short sentences, "And"/"But" starts, one-line paragraphs, occasional fragments. So those patterns alone won't trigger flags — the issue is what they're stacked with. - -### Step 2 — Pattern scan - -**Issues Found** - -- **[HIGH]** "Most leaders think hiring is a numbers problem. / It isn't." — Dramatic reframe variant (§3.1) -- **[HIGH]** "Hiring is a clarity problem." — Definition reframe; relabels without adding info -- **[HIGH]** Three-sentence anaphora "When you don't know..." (§3.13) — One is rhythm, three is AI -- **[HIGH]** "Here's the truth:" — Performative directness (§3.4) -- **[HIGH]** Tricolon "They define the role. They define the bar. They define the trade-offs." — Compulsive tricolon (§5) -- **[HIGH]** "It's not magic. It's discipline." — Manufactured punchline (§3.2) -- **[MEDIUM]** "What's something you've learned about hiring that took you too long to figure out?" — Engagement-bait closer (§5) - -### Step 3 — Severity gate - -Six pattern categories triggered, no Tier 1 vocab hits, sentence lengths varied. Pattern density alone is enough — **full rewrite** (the structure is the AI tell here, not vocabulary). - -### Step 4 — Rewrite - -``` -The first time I missed a hire badly, it cost us six months. -We knew we needed someone in the role. We didn't know what the role was — -we just knew the work wasn't getting done. So we hired for raw talent and -trusted that "they'd figure it out." They didn't. Not because the person -wasn't good, but because we kept moving the target. - -The fix wasn't moving slower. It was getting honest with ourselves about -the role before we wrote the JD: what would the first 90 days actually -produce? What were we willing to give up to get those things? Who, on our -team, would lose responsibility when this person joined? - -When we wrote those down, the hiring loop got faster, not slower. We -turned away two people we would have hired six months earlier. The third -one is still on the team three years later. -``` +## Issues Found -### Step 5 — Self-audit +- [HIGH] "Here's the truth" and "It's not magic. It's discipline" add theatrical framing without a distinct claim. -> "What makes the above so obviously AI generated?" +## Rewritten Draft -- None detected. The post leads with a specific story (six months, third person three years), avoids reframes, and uses the author's natural cadence (varied sentences, one "And"-style continuation that fits, no manufactured closer). +The best leaders I've worked with hire slowly. They define the role, the bar, and the trade-offs before choosing someone. -### Final Version +## What Changed -(same as above) +- Removed or replaced the flagged phrasing while retaining the substantive claims and intent. -### Humanizer Report +## Self-Audit -- **Channel detected:** linkedin (personal) -- **Voice loaded:** author profile -- **Rewrite depth:** full -- **Clean-but-hollow:** no (specific failure, specific timeline, specific outcome) -- **Notes:** rewrote opener to a real story instead of a reframe; cut anaphora, tricolon, and manufactured punchline; replaced engagement-bait closer with a concrete result the reader can react to +Names, numbers, qualifications, and asks match the input. No anecdote or outcome was added. The existing register remains; no voice match is claimed. ---- +## Final Version -## What this example shows +The best leaders I've worked with hire slowly. They define the role, the bar, and the trade-offs before choosing someone. -The original post used **zero** Tier 1 vocab words. It still read as obviously AI-generated because it leaned on six structural patterns at once. Vocabulary scrubbers wouldn't have flagged any of it. +## Humanizer Report -That's why Humanizer scans structural-first. +- Channel detected: linkedin +- Voice loaded: none +- Rewrite depth: patch +- Clean-but-hollow: no; the point is understandable, though supporting examples could strengthen it +- Notes: Keep the author's actual opinion about hiring slowly. Do not reverse it or invent a failed hire, a six-month delay, or a successful employee. The three-item list names distinct concepts and stays. diff --git a/examples/voice-calibration.md b/examples/voice-calibration.md new file mode 100644 index 0000000..10c1abf --- /dev/null +++ b/examples/voice-calibration.md @@ -0,0 +1,34 @@ +# Worked example: calibrating without importing facts + +All text below is synthetic. The sample supplies style evidence only. + +## Request + +Humanize the draft for an internal email using this sample. Keep em dashes and "But" openings. Do not save a profile. + +## Voice sample + +The export failed again. But we have a workaround — use the saved report while the team investigates. I would rather send the numbers late than send the wrong ones. + +## Draft + +The review could potentially take until Friday. But the source file is missing — we need it before we can finish. Please send the file. + +## Calibration + +| Dimension | Evidence and decision | +|---|---| +| Sentence rhythm | "The export failed again" is brief; the explanation has more room. Preserve the functional mix. | +| Word choice | "workaround" and "saved report" are concrete. Keep plain operational language. | +| Paragraph openings | The sample starts directly with an event. Keep a direct opening. | +| Punctuation | The user explicitly permits em dashes. Preserve the draft's dash; the sample alone would not establish a rate. | +| Recurring phrasing | The user explicitly preserves "But" openings. No other recurring phrase can be inferred from one sample. | +| Transitions | "But we have a workaround" connects a problem to a next step. Preserve meaningful connections. | + +## Candidate edit + +The review could take until Friday. But the source file is missing — we need it before we can finish. Please send the file. + +## Post-edit check + +Only the redundant "potentially" was removed. "Could" preserves uncertainty, Friday remains, the missing-file dependency remains, and the ask is unchanged. The dash and "But" opening survive despite generic style defaults. No export failure or report from the sample was imported into the draft. Calibration was not saved. diff --git a/install.sh b/install.sh index fc0b2e6..12aede1 100755 --- a/install.sh +++ b/install.sh @@ -54,13 +54,19 @@ if [[ -f "${DEST_FILE}" ]]; then fi cp "${SOURCE}" "${DEST_FILE}" -cp -R "${REFERENCES_DIR}" "${DEST_DIR}/references" +# Copy contents into stable destinations so repeat installs do not nest folders. +for resource in references examples docs; do + mkdir -p "${DEST_DIR}/${resource}" + cp -R "${SCRIPT_DIR}/${resource}/." "${DEST_DIR}/${resource}/" +done +cp "${SCRIPT_DIR}/ATTRIBUTION.md" "${DEST_DIR}/ATTRIBUTION.md" echo "" echo "Humanizer installed to ${DEST_DIR}" echo " - SKILL.md (core)" -echo " - references/ (progressive-disclosure files: patterns.md, channels.md)" +echo " - references/ (progressive-disclosure files: patterns, channels, voice calibration)" echo "" +echo " - examples/ and docs/ (voice setup and worked examples)" echo "Try it:" echo " In Claude Code, type: /humanizer" echo " Or: humanize this draft" diff --git a/references/channels.md b/references/channels.md index 0ab00ce..72ddfb8 100644 --- a/references/channels.md +++ b/references/channels.md @@ -28,27 +28,29 @@ Strongest cue wins. If two cues point to different channels, ask rather than gue ## Channel × Strictness Matrix -**S** = strict (flag), **R** = relaxed (house style — don't flag), **I** = inverted (required), **N** = normal. +Approved voice and instructions for this draft outrank every default in this table. Do not infer a required pronoun or persona from the channel alone. + +**S** = strict (flag), **R** = relaxed (house style — don't flag), **I** = format convention (subject to the request), **N** = normal. | Channel | One-line paras | Staccato | "We" voice | First-person "I" | Voice profile to load | |---|---|---|---|---|---| | Newsletter (editorial) | R | R | N | R | brand or author | -| Blog post / case study | S | S | I | S | brand | -| Marketing email | N | N | I | S | brand | +| Blog post / case study | S | S | N | N | brand | +| Marketing email | N | N | N | N | brand | | Email (1:1) | N | N | N | R | author | -| LinkedIn — personal | R | R | N | I | author | +| LinkedIn — personal | R | R | N | R | author | | LinkedIn — organizational | R | R | N | R | brand | | Slack (team or 1:1) | R | R | N | R | author | | Meeting agenda | I (bullets) | N | N | N | none (format rules apply) | | Feedback / coaching note | R | R | N | R | author | -| Landing page / ad | R | R | I | S | brand | -| Reddit reply | R | R | N | R (required) | none (anonymous register) | +| Landing page / ad | R | R | N | N | brand | +| Reddit reply | R | R | N | R | none (anonymous register) | --- ## Per-Channel Hollow Failure Modes -A draft can pass the AI-tells scan and still fail. Flag `[HOLLOW]` if: +Assess substance against the draft's purpose. These are diagnostic cues, not required ingredients: a notification need not contain an ask, a useful qualitative example need not contain a number, and an agenda may legitimately include time estimates. Flag `[HOLLOW]` when missing information prevents the piece from doing its job: | Channel | Hollow failure mode | |---|---| @@ -59,7 +61,7 @@ A draft can pass the AI-tells scan and still fail. Flag `[HOLLOW]` if: | LinkedIn — organizational | Predicts audience pain instead of reporting what was observed; generic platitude | | Slack — team | Over-explains context before the ask; ask buried | | Slack — 1:1 (terse register) | More than 2 sentences of preamble before the point | -| Meeting agenda | Bullets without owners; talk tracks or time estimates present | +| Meeting agenda | Decisions or actions whose owners are unclear | | Landing page / ad | No specific proof point (stat, customer, outcome) above the fold | | Feedback note | Abstract ("be more proactive") without the specific behavior + moment | | Reddit reply | Generic hot-take without a specific counter-point or personal experience; reads like it was written without reading the thread | @@ -68,14 +70,7 @@ A draft can pass the AI-tells scan and still fail. Flag `[HOLLOW]` if: ## When to Ask vs. Decide -**Auto-decide** when ≥2 cues agree. **Ask** when: -- Only one weak cue matches -- LinkedIn detected but voice ambiguous between personal and organizational -- Email detected but register unclear (marketing blast vs. 1:1) -- Slack detected but audience unclear (team channel vs. terse 1:1 — strictness differs) -- Draft <50 words with no format cues - -Ask format: *"Looks like [channel A] or [channel B]. Which — and who's the audience?"* Never guess on audience; channel strictness pivots on it. +Infer the channel from the request and the strongest cues. Ask only when two plausible channels or audiences would materially change the edit. With weak cues and no consequential conflict, preserve the draft's register and note the assumption instead of requiring an interview. --- @@ -90,6 +85,8 @@ Some patterns look AI-ish in isolation but are part of an author's actual voice. - **Hyphens with spaces** instead of em dashes, if the author or brand profile specifies it. - **Specific terms of address or honorifics** the audience expects (titled professionals, formal salutations) — load these from the voice profile. -The test: would this pattern read as natural if the author spoke it out loud? If yes, leave it. If the piece is client-facing brand voice (blog post, case study, landing page), these carve-outs tighten — default to the Channel × Strictness Matrix above. +The test is whether the pattern serves the intended voice and audience. Approved brand exceptions also outrank the matrix. Use the matrix only where no applicable voice guidance decides the issue. If no voice profile is loaded, treat the patterns above as low-priority — flag only when stacked with other tells. + +For evidence-based calibration, read `references/voice-calibration.md`. Preserve code and expected results in procedures; do not rewrite regular instructions merely to vary cadence. diff --git a/references/patterns.md b/references/patterns.md index fe20899..ead4b79 100644 --- a/references/patterns.md +++ b/references/patterns.md @@ -13,24 +13,24 @@ Trigger full rewrite when **all three** are true: - 3+ distinct pattern categories triggered - Uniform sentence length — three-plus consecutive sentences within 2 words of each other -Otherwise patch mode. Patching only smooths the surface; the skeleton is still AI-shaped if the threshold is hit. +Uniform cadence across the piece can also warrant restructuring when it weakens comprehension. Otherwise patch. These thresholds are editorial cues; approved voice, short messages, and deliberate procedure formats can justify regularity. --- ## 2. CRITICAL Patterns (P0) — Credibility Killers -These lose the reader's trust in one sentence. Always fix. No judgment call. +Address credibility problems explicitly. Missing evidence alone does not establish fabrication. Preserve unverified claims and flag them; correct or remove them only with supplied evidence or user authorization, disclosing the change. | Pattern | What it is | Fix | |---|---|---| -| **Fabricated stats / fake specificity** | Precise-sounding numbers with no real source ("studies show 73% of teams..."). | Cut, or replace with a real cited figure. Never approximate to sound authoritative. | -| **Fake attributions** | Quotes or claims attributed to an expert/study that doesn't exist or doesn't say that. | Verify the source says the exact thing. If not, cut. | -| **Knowledge-cutoff disclaimers** | "As of my last update..." / "I may not have the latest..." | Delete entirely. | +| **Fabricated stats / fake specificity** | Precise-sounding numbers with no real source ("studies show 73% of teams..."). | Flag for verification. Replace only from supplied evidence, with attribution; disclose any correction. | +| **Fake attributions** | Quotes or claims attributed to an expert/study that doesn't exist or doesn't say that. | Check supplied evidence; flag uncertainty. Disclose a supported correction instead of silently cutting. | +| **Knowledge-cutoff disclaimers** | "As of my last update..." / "I may not have the latest..." | Remove generic chatbot framing, but retain any real date or uncertainty limitation. | | **Chatbot artifacts** | "Let me know if you'd like me to expand...", "I hope this helps!", "Happy to revise." | Delete. Never ships in final copy. | | **Sycophancy** | "Great question!", "That's a fantastic point..." | Delete. | **BEFORE (fabricated stats):** "Studies show that 73% of B2B teams lose revenue to onboarding friction, with most seeing a 12% hit to deal velocity annually." -**AFTER:** "In the teams we've worked with, onboarding friction typically costs 3–8% of pipeline velocity — not catastrophic, but meaningful at scale." (Cites experience over invented precision.) +**ACTION:** Flag both figures and their attribution for verification. Without evidence, preserve the claim as unresolved in the report; do not invent a replacement range or first-hand experience. **BEFORE (chatbot artifact at end of email):** "Let me know if you'd like me to expand on any of this, or if you'd prefer I tighten it further!" **AFTER:** (Delete entirely. Sign off cleanly with the writer's actual close.) @@ -45,7 +45,7 @@ The high-signal structural tells. In rough order of severity: "That's not X. That's Y." — where Y adds no new information, just relabels X for effect. - **BEFORE:** "This isn't a hiring problem. This is a process problem." -- **AFTER:** "The hiring gap is downstream of the process — fix the intake handoff and the headcount math changes." +- **AFTER:** "The hiring problem comes from the process." Variant: **Definition reframes** — "It's an execution problem dressed up as a strategy problem." Same mechanic, same fix: say the actual thing. @@ -53,16 +53,13 @@ Variant: **Definition reframes** — "It's an execution problem dressed up as a Section or piece ends on a tidy aphorism that sounds quotable but doesn't say anything. Includes **orphan closers** (one-line dramatic endings) and **section-ending zingers**. - **BEFORE:** "Because in customer success, the details aren't details. They're everything." -- **AFTER:** "Miss the kickoff agenda and renewal probability drops 15 points. That's most of the variance between a 90% and 105% net retention number." +- **AFTER:** "Details matter in customer success." Flag the missing example; do not invent an effect size. -### 3.3 Cadence & Structural Regularity — the #1 detector signal -Uniform rhythm is the strongest signal a statistical classifier keys on, and the one a polishing pass most often makes worse. Two layers: +### 3.3 Cadence and paragraph regularity -**Sentence cadence (burstiness).** Human writing swings between short, medium, and long sentences; AI and over-polished prose cluster near one length. Flag when three-plus consecutive sentences land within 2 words of each other, or when most of the piece sits inside a single 15–25-word band. Target a visibly mixed distribution — some sentences under 8 words, some over 30. Read-aloud test: if it scans like a metronome, it is too regular. +Check repeated sentence shapes and same-sized paragraphs when they make the piece monotonous. Three consecutive sentences within two words of each other can prompt a closer read; it is not proof of machine authorship or an automatic failure. -**Paragraph shape.** Evenly-sized paragraphs (nearly every one 3–4 sentences of similar length) read as machine-built. Vary it — let a one-line paragraph sit next to a dense one. - -Rule of thumb: **no three consecutive same-length sentences, and no long run of same-shape paragraphs.** Fix this by *increasing* variance, never by evening the rhythm out. This is the highest-signal structural tell in the catalog — check it on every pass, and treat a uniform-cadence draft as a full-rewrite trigger (§1) even when the vocabulary is already clean. +Repair rhythm in two passes. First assign each sentence its job and give explanations room while keeping pivots brief. Then cut filler inside those sentences. Merge or split where meaning benefits; never pad to force variance. Preserve deliberate parallelism, short messages, consistent instructions, and approved voice choices. ### 3.4 Performative Directness "Here's the truth." / "Let's be real." / "The reality is..." — throat-clearing dressed as candor. @@ -77,7 +74,7 @@ Rule of thumb: **no three consecutive same-length sentences, and no long run of Vague hype sentence that exists only to set up the real sentence that follows. - **BEFORE:** "The stakes have never been higher. Companies are facing unprecedented pressure on margins." -- **AFTER:** "Companies are facing margin pressure — pricing power is flat while labor costs are up double digits since 2021." +- **AFTER:** "Companies are facing pressure on margins." ### 3.7 Persuasive Authority Tropes "The real question is...", "At its core...", "Fundamentally...", "What this really means is...". Authority-by-assertion with no earned authority behind it. Delete and state the thing. @@ -86,7 +83,7 @@ Vague hype sentence that exists only to set up the real sentence that follows. "No guessing. No wasted motion. No hand-offs that fall apart." Three-or-more negations tacked onto a claim. Reads like landing-page copy from any vendor. - **BEFORE:** "We take over the migration. No handoffs. No dropped data. No surprises." -- **AFTER:** "We take over the migration on day one. The previous vendor's unfinished work is ours to close." +- **AFTER:** "We take over the migration without handoffs, dropped data, or surprises." Preserve these promises and flag them if they need verification. ### 3.9 Elegant Variation / Synonym Cycling The same thing named four different ways to avoid repetition — "the customer / the client / the partner / the organization". Readers notice. Pick one noun and repeat it. @@ -101,16 +98,16 @@ Ends on uplift that wasn't earned by the preceding text. Usually starts with "Bu "I'll be honest..." / "Can I be real for a second?" / "Not gonna lie..." Performative candor as a credibility grab. Delete and say the honest thing directly. ### 3.13 Anaphora / Repetitive Negation -"Not the vendor. Not the timeline. Not the scope." Three-plus parallel openers with the same word. One is rhythm. Three is AI. +"Not the vendor. Not the timeline. Not the scope." Three-plus parallel openers with the same word. Repeated openings merit review when they add emphasis without meaning; deliberate parallelism can stay. ### 3.14 Universal Authority Without Source -"Industry experts agree...", "Studies show...", "It's well known that..." — no citation. Either add the source or cut the claim. +"Industry experts agree...", "Studies show...", "It's well known that..." — no citation. Use a supplied source or flag the attribution for verification; do not invent one or silently remove the claim. ### 3.15 Fragmented Headers Heading followed by a one-line restatement of the heading before the real content starts. - **BEFORE:** `### The transition is fast` followed by "Our transitions are fast. Here's why:" -- **AFTER:** `### The transition is fast` followed by "Most customers are fully on the new system within three to six weeks..." +- **AFTER:** `### The transition is fast` followed by the existing explanation, with the redundant restatement removed. Preserve any facts that appeared only in the removed sentence. ### 3.16 Credential-Stacking / Stat-Bomb / Tension-Colon Openers Opening patterns to avoid: @@ -119,7 +116,7 @@ Opening patterns to avoid: - **Tension colon:** "The dirty secret of the industry: vendors don't actually want you to leave." - **Common-belief-then-counter:** "Everyone says switching vendors is risky. It isn't." -All of these signal "blog post written by AI." Open on a number tied to a specific situation, a named person or company, or a specific observation instead — "Lisa's team cut deployment time from four hours to twenty minutes" beats any of the four openers above. +These can make an opener formulaic; none establishes authorship. Open on a number tied to a specific situation, a named person or company, or a specific observation instead — "Lisa's team cut deployment time from four hours to twenty minutes" beats any of the four openers above. --- @@ -127,11 +124,11 @@ All of these signal "blog post written by AI." Open on a number tied to a specif **Domain-terminology exemption:** Industry-specific metrics, technical codes, regulatory terms, and legal language are exempt from Tier 2/3 density checks. "Significant" in a clinical finding, "crucial" in a compliance clause, or "critical" in an incident report are precise, not filler. Apply the tiers to general prose only — not to technical claims, quoted regulations, or domain vocabulary the audience will read as load-bearing. -### Tier 1 — Always Replace (5–20x more common in AI than human writing) +### Tier 1 — Replace generic use delve, pivotal, multifaceted, myriad, plethora, robust, seamless, leverage, unlock, unleash, harness, empower, embark, realm, landscape (metaphorical), tapestry, beacon, illuminate, bolster, meticulous, elevate, streamline, groundbreaking, transformative, unprecedented, game-changer -No judgment call. Cut or swap every time. +Replace generic use unless approved voice calls for it. All tiers exempt precise domain terms, code, quotations, legal text, proper names, and examples discussing the term itself. ### Tier 2 — Flag in Clusters (2+ in same paragraph) @@ -145,11 +142,11 @@ significant, innovative, effective, dynamic, scalable, compelling, exceptional, These are real English words. Only flag when the draft leans on them as a crutch — if three+ appear in 100 words, the draft has no specific nouns to stand on. -### Filler Qualifiers — Always Cut +### Filler qualifiers — cut only when meaning is unchanged arguably, notably, importantly, essentially, fundamentally, truly, really, very, simply, just (as softener), quite, rather, somewhat -Exceptions: "just" meaning "only/recently" ("we just launched"). "really" in quoted dialogue. +Preserve any qualifier that changes certainty, extent, or timing. "Arguably" can mark a debatable claim; "somewhat" can limit its degree; "just" can mean only or recently. Keep quoted dialogue verbatim. --- @@ -164,7 +161,7 @@ Exceptions: "just" meaning "only/recently" ("we just launched"). "really" in quo | **Colon-heavy titles** | "The Onboarding Revolution: Why Teams Need a New Playbook". Pick one clause. | | **Only 2nd/3rd person voice** | Vary — use "we" when it's a first-party claim. | | **Puffing up importance** | "It's critical that..." / "Now more than ever..." Delete the puff. | -| **Generic/vanilla tone** | No specific numbers, names, or examples. Add one concrete detail per paragraph. | +| **Generic/vanilla tone** | No specific numbers, names, or examples. Use a supplied concrete detail where relevant, or flag the gap. | | **Hyphenated word-pair over-consistency** | "data-driven, outcomes-focused, customer-centered" stacked. Pick one. | | **Superficial -ing analyses** | "By focusing on X, teams can achieve Y" — vague cause-effect. Name the mechanism. | | **Arrow chains** | "Research → draft → review → publish". Fine once; tic if repeated. | @@ -179,7 +176,7 @@ Exceptions: "just" meaning "only/recently" ("we just launched"). "really" in quo ## 6. Quantified Punctuation Budgets -Hard caps per piece. Going over one is usually a sign of an unearned rhythm. +Default review budgets. Approved voice and explicit punctuation preferences override them in either direction. Preserve ranges, quotations, code, and legal text. | Mark | Budget | Notes | |---|---|---| @@ -201,4 +198,18 @@ Never ship a piece that opens with: - "When it comes to..." - "Whether you're X or Y..." -If you find one, cut the opener and start on the second paragraph — 90% of the time it's the real opener. +If you find one, cut the opener and start on the second paragraph — it may contain the real opener. Preserve any unique information from the cut sentence. + +## 8. False positives and protected content + +Perfect grammar, a single dash, one short sentence, formal vocabulary, a useful disclaimer, and consistent formatting are not evidence of authorship. Watch density and function. Preserve technical terms, quotations, code, legal language, and examples discussing a flagged phrase. + +Keep real specificity, mixed feelings, unresolved tension, dated references, and genuine self-corrections. Do not replace an awkward but meaningful detail with a generic line. Page labels such as "How it works" and real question-shaped CTAs can be useful navigation. + +## 9. Claim-preservation check + +Before emitting, compare names, numbers, dates, quotations, citations, rankings, negations, qualifications, and asks against the input. Any change needs a reason grounded in supplied evidence or the user's request. Compression can combine claims; it cannot lose them. + +Input: "We may finish Friday. Tuesday is no longer possible. Please confirm the scope." +Safe edit: "We may finish Friday; Tuesday is no longer possible. Please confirm the scope." +Unsafe edit: "We'll finish Friday. Please approve the budget." It upgrades uncertainty, drops a constraint, and changes the ask. diff --git a/references/voice-calibration.md b/references/voice-calibration.md new file mode 100644 index 0000000..037a7e4 --- /dev/null +++ b/references/voice-calibration.md @@ -0,0 +1,38 @@ +# Voice calibration + +Read when a voice sample, profile, or upstream voice instruction applies. Ordinary editing does not require an interview. + +## Select the source + +Identify the publisher and audience from the request. Use instructions for this draft first, then that publisher's approved guide or sample, then applicable upstream guidance. Explicit preferences beat habits inferred from samples. Ask if two authoritative sources conflict in a way that would change the result. + +Read an existing profile as written. Accept a path, pasted text, or a source the host can access. Do not assume a fixed home directory, profile schema, CLI flag, or environment variable. Report unreadable sources instead of claiming to have loaded them. + +## Calibrate from evidence + +Record these six observations for the current pass. Support each with a short excerpt or a profile section. Use "insufficient evidence" when appropriate. + +| Dimension | Observe | Preserve | +|---|---|---| +| Sentence rhythm | Short pivots, longer explanations, deliberate fragments | Each sentence's function; avoid forced length targets | +| Word choice | Technical precision, contractions, colloquial or formal register | The author's vocabulary level and domain terms | +| Paragraph openings | Direct claims, greetings, connective openings | Chosen openings that serve the audience | +| Punctuation | Explicit preferences and recurring habits | Approved exceptions to generic budgets | +| Recurring phrasing | Characteristic turns of phrase and terms of address | Phrases with a purpose, without copying them everywhere | +| Transitions | Direct continuation, asides, questions, explicit links | The way the writer moves between ideas | + +Use the sample from the closest channel when several are available. A chat sample alone does not establish how its author writes a legal notice or a brand page. A single dash is insufficient to infer a punctuation rate. Never infer personality, biography, or a permanent preference from a small sample. + +## Apply and verify + +Style guidance does not supply facts for the draft. Never transplant a sample's anecdote, number, identity, or opinion into the edit. Keep quotations, legal text, code, and identifiers intact. + +Approved style overrides generic channel defaults and word-watch lists. When a deliberate choice conflicts with a heuristic, preserve it and note the exception once. Do not re-flag a span the user asked to keep. + +Compare the candidate against all six observations after rewriting. Restore any deliberate rhythm, warmth, qualification, or unusual detail lost through editing. Under Humanizer Report, use the existing Voice loaded and Notes fields to name the source, its limits, and the exceptions preserved. Do not add required output headers. + +## Optional setup + +If the user requests setup, use the interview in SKILL.md. Samples establish observed habits; explicit answers establish stated preferences. Label that difference. If samples are skipped, record preferences only and say the profile is uncalibrated. Never fill blank sections with invented habits. + +Saving or changing a persistent profile requires the user's request. Otherwise the observations last only for this draft. Repeated "stet" decisions can justify suggesting a profile update, never silently applying one. From b0b2c95c56247e86a8f169690150ecbc1b0f2c95 Mon Sep 17 00:00:00 2001 From: Michael Lock Date: Tue, 15 Sep 2026 10:19:37 -0700 Subject: [PATCH 2/2] Finalize v1.2.0 release metadata --- CHANGELOG.md | 2 +- README.md | 2 +- docs/release-1.2.0.md | 12 ++++-------- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ed28b5..827e22f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project will be documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows semantic versioning. -## [1.2.0] - Unreleased +## [1.2.0] - 2026-09-15 ### Added - Evidence-based voice calibration with six observations, explicit source precedence, and a post-edit voice comparison. diff --git a/README.md b/README.md index b00d73e..40a69bd 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ It's not a stylechecker. It's a final pre-delivery pass that runs before you cli --- -## v1.2.0 release candidate +## New in v1.2.0 Voice calibration now selects the publisher's guide or sample, records six evidence-based observations, and checks the edited draft against them. Existing profile formats work without conversion. An ordinary scrub needs no setup interview. diff --git a/docs/release-1.2.0.md b/docs/release-1.2.0.md index 0feaf28..0d6a1a3 100644 --- a/docs/release-1.2.0.md +++ b/docs/release-1.2.0.md @@ -1,6 +1,6 @@ -# v1.2.0 release preparation +# v1.2.0 release validation -Status: release candidate, not tagged or published. The changelog is intentionally Unreleased. +Release date: 2026-09-15. Publication is tracked on the [GitHub release](https://github.com/milock/humanizer/releases/tag/v1.2.0). ## Scope @@ -16,10 +16,6 @@ Calibrate from the intended publisher's voice source, preserve claims and asks, - One forward exercise preserved a date, number, uncertainty, request, technical term, code, and explicit punctuation preferences without editing them. - Two qualitative baseline/current simulations covered a hollow update and competing brand/personal profiles. Both versions could return safe output; the new version removes contradictory instructions. These are reviewer exercises, not controlled model benchmarks or evidence of a measured quality gain. -## Release steps +## Publication -1. Review and merge the release pull request after CI passes. -2. Replace Unreleased with the actual release date and remove the README's release-candidate label. -3. Tag the reviewed commit as v1.2.0 and publish release notes based on CHANGELOG.md. - -No tag or published release is part of this preparation. +Michael approved publication on 2026-09-15. The release uses the reviewed pull request and its passing CI result; the tag points to the merged commit.