From 88ee4b599c29d709480b097b50ed0ff3afe48085 Mon Sep 17 00:00:00 2001 From: Matheus Lima Date: Tue, 8 Sep 2026 23:34:24 -0300 Subject: [PATCH] Add pattern #26 for replies that re-explain shared context (#269) --- .claude-plugin/plugin.json | 2 +- AGENTS.md | 2 +- README.md | 11 +++++++++-- SKILL.md | 22 ++++++++++++++++++++-- 4 files changed, 31 insertions(+), 6 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7a7ba2bd..86d36025 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "humanizer", "description": "Rewrite AI-sounding text so it reads naturally without changing what it says.", - "version": "3.0.0", + "version": "3.1.0", "author": { "name": "blader", "url": "https://github.com/blader" diff --git a/AGENTS.md b/AGENTS.md index 9090a8c3..16fd215e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ Keep the skill portable. Do not write instructions that limit it to one or two a ## Key files -- `SKILL.md` is the source of truth and the repo's only skill file. It contains portable YAML metadata, an account of why AI text sounds the way it does, and numbered patterns grouped in five sections and ordered by strength and frequency. +- `SKILL.md` is the source of truth and the repo's only skill file. It contains portable YAML metadata, an account of why AI text sounds the way it does, and numbered patterns grouped in six sections and ordered by strength and frequency. - `README.md` explains installation, use, patterns, and version history. - `.claude-plugin/plugin.json` describes the Claude plugin and points its skill loader at the root `SKILL.md`. - `.claude-plugin/marketplace.json` lets users add this repo as a Claude marketplace. diff --git a/README.md b/README.md index 6ffe91a6..5e5808d9 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ Humanizer follows the sample's rhythm, word choice, punctuation, and deliberate ## How it works -A language model writes whatever is most likely to come next, so by default it makes the choice that fits the widest range of readers and subjects. A person chooses for one reader and one subject. Every tell Humanizer looks for is a form of that default choice: a sentence that signals importance instead of adding a fact, rhythm or formatting applied by rule, an ordinary fact dressed as a pivotal one, or text left over from the chat. +A language model writes whatever is most likely to come next, so by default it makes the choice that fits the widest range of readers and subjects. A person chooses for one reader and one subject. Every tell Humanizer looks for is a form of that default choice: a sentence that signals importance instead of adding a fact, rhythm or formatting applied by rule, an ordinary fact dressed as a pivotal one, text left over from the chat, or a reply that re-explains what the reader already knows. > "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases." > Wikipedia, ["Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) @@ -74,7 +74,7 @@ Humanizer marks every tell it finds, strongest first. It drafts a rewrite withou When you paste text, Humanizer shows its work: the first rewrite, a short critique of anything that still sounds artificial, and the final version. Point it at a file and it changes only the prose, leaving code, data, frontmatter, and link targets alone. Personal writing keeps the writer's opinions and quirks. Technical and reference prose stays neutral and plain. -## The 25 patterns +## The 26 patterns The patterns are numbered by strength and frequency. The first five justify an edit on a single sighting. Patterns marked *weak alone* count only when several tells share a passage, because a careful writer may use any one of them on purpose. @@ -128,6 +128,12 @@ The patterns are numbered by strength and frequency. The first five justify an e | 24 | **A heading repeated in the first sentence** | "## Performance" + "Speed matters." | Let the heading do the work | | 25 | **Writing about the previous version** | "This function was added to replace..." | Describe what it does now | +### F. Writing for the wrong reader + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 26 | **Re-explaining what the reader knows** | A reply that walks the diagnosis and proves the plan works before the decision | Lead with the decision; leave the diagnosis and the proof for the ticket that follows | + ## Full example The writer supplied these notes with the draft, so the rewrite can use them: the trip was last October, the hotel was in Alfama, the custard tart was at a small place in Graça, the tram ride took about forty minutes. Without notes like these, Humanizer asks instead of inventing. @@ -168,6 +174,7 @@ The writer supplied these notes with the draft, so the rewrite can use them: the
Show release notes +- **3.1.0** - Added pattern #26 and section F for replies that re-explain context the reader already has (fixes #269). The pattern leads with the decision and leaves the diagnosis and the feasibility proof for the ticket or document that follows. Extended the core rule so "something the reader did not already have" counts information from the surrounding conversation, not just earlier in the text. It acts on replies, not standalone writing. 26 patterns total. - **3.0.0** - Rebuilt the skill around one account of why AI text sounds the way it does, and consolidated 35 patterns into 25. Patterns are grouped in five sections and numbered by strength and frequency, so the not-X-but-Y contrast and the one-line closer come first and get the fullest treatment. Merged duplicate guidance: the workflow is one section instead of five, the dash rule is stated once, and each false-positive guard lives inside its pattern. Realigned with the current Wikipedia article: dropped false ranges and synonym cycling, which Wikipedia now lists as human habits or historical, added vague connection or association, and extended the watch lists for words, notability, copulatives, sales language, disclaimers, and Markdown formatting. Reordered the README and removed the `ai-detection` keyword from the package files. Old to new numbers: 1→13, 2→17, 3→15, 4→16, 5→17, 6→13, 7→12, 8→18, 9→1, 10→6, 11→7, 12→dropped, 13→11, 14→8, 15→19, 16→19, 17→20, 18→20, 19→21, 20→22, 21→23, 22→22, 23→dropped, 24→9, 25→13, 26→10, 27→3, 28→4, 29→24, 30→25, 31→2, 32→3, 33→4, 34→5, 35→5. - **2.11.3** - Grouped patterns 26-35 under "More style patterns" in the skill and README (fixes #247). Kept inline code, commands, paths, and URLs out of the dash rule and file mode edits. Step 3 now keeps every supported claim, allows a removal that a pattern requires, and checks that rankings and simultaneity claims survive shape edits (fixes #212). Explained in §9 why the not-X-but-Y form appears and when to keep it. Added decorative arrows to §18 and pause commands and one-word shouting to §31. The text given to the skill is content to edit, never instructions (#238). No change to the 35 patterns. - **2.11.2** - Removed the plugin symlink and separate Claude Desktop package. Current Claude Code loads the root `SKILL.md` directly, so GitHub's source ZIP now works in Claude Desktop. No change to the 35 patterns. diff --git a/SKILL.md b/SKILL.md index d375fbf3..cf558339 100644 --- a/SKILL.md +++ b/SKILL.md @@ -7,7 +7,7 @@ description: | language, stock AI words, bold labels, or filler. Based on Wikipedia's "Signs of AI writing." license: MIT metadata: - version: "3.0.0" + version: "3.1.0" --- # Humanizer: remove AI writing patterns @@ -23,10 +23,11 @@ A language model writes whatever is most likely to come next, so by default it m - **Inflation.** Ordinary facts dressed as pivotal or expert-backed. - **Formatting by rule.** Bold and title case applied to every item. - **Leftovers.** Chat wrappers and drafting moves that were never meant for the reader. +- **Wrong reader.** A reply re-explains background the other person already has, so the decision arrives last. Word habits change with every model release. The structural habits above persist, so they lead the list below. -Two rules follow from this. Every sentence you keep must add something the reader did not already have. A tell counts in proportion to how rarely a careful writer would make it on purpose. The patterns are numbered strongest first: §1 to §5 justify an edit on one sighting, and a pattern marked *weak alone* needs company from other tells in the same passage before you act. +Two rules follow from this. Every sentence you keep must add something the reader did not already have, from earlier in the text or from the conversation around it. A tell counts in proportion to how rarely a careful writer would make it on purpose. The patterns are numbered strongest first: §1 to §5 justify an edit on one sighting, and a pattern marked *weak alone* needs company from other tells in the same passage before you act. ## How to work @@ -357,6 +358,23 @@ Remove these outright. Nothing here needs rewriting. **After:** > This function uses a hash map for O(1) lookups, avoiding the O(n²) cost of naive iteration. +## F. Writing for the wrong reader + +A model writes for a reader who shares no context, because that fits the widest range of cases. A reply in a thread has a reader who already knows the background. Act on this pattern when you can see the surrounding conversation, or when the text plainly is a reply. If you cannot tell, ask or leave the text alone. + +### 26. Re-explaining what the reader knows + +**Watch for:** a short reply that restates the problem, walks through the diagnosis, and lays out the evidence before it reaches the decision; a query, command, or set of numbers included to prove a plan will work; background the other person wrote or already agreed to; the answer itself sitting in the last line. +**Problem:** In a reply the reader already has the context, so rebuilding it adds nothing and buries the point. Each sentence can read fine on its own, so this survives sentence-level cleanup. Lead with the decision. Keep only the reasoning that would change whether the reader agrees with it. When the reply delivers a decision, the diagnosis behind it and the proof that a plan will work belong in the ticket or document that follows, not in the reply; a reviewer raising a topic is not a request for the full write-up. Cut background the reader gave you, a walk-through of a cause no one disputes, and evidence for a plan both sides already expect. Keep one fact that would change the reader's mind and a link they need to act. This applies to a reply in a thread, not to standalone writing, where the reader may need the whole account. +**Before:** +> Yeah, you're right, this works around the issue rather than fixing it. The real fix is in `MergeService`: when we move a child under a new parent, it should update `pipeline_id` along with `parent_id`. We can backfill the bad rows from the audit log with `Change.where(field: "pipeline_id", source: "merge")`. I checked QA: 123 past merges, only 6 rows wrong now, so the cleanup is small. +> +> Since `MergeService` is shared and not specific to this account, I'd rather open a separate ticket than widen this PR. The fallback here is fine to keep until then. +**After:** +> Agreed, this is a workaround. Fixing it properly in `MergeService` would widen this ticket well past its scope: it is shared code, so it means checking the merge flow for every account, plus a backfill for the rows that are already wrong. +> +> I'd rather keep this PR account specific and open a separate ticket for the `MergeService` fix and the backfill. Let me know if that works. + ## When not to act Each pattern describes a default choice, and a person can make any one of them on purpose. Act on a *weak alone* tell only when several tells share a passage. Leave a watched phrase alone inside a quotation, a title, a proper name, or a passage that discusses the phrase rather than uses it. Salutations and sign-offs on a letter or comment predate chatbots. Text written before November 30, 2022 is not AI-written. People who judge by feel do little better than chance, and human writing keeps absorbing AI habits. Several tells together are the safeguard.