From cfaf3139aed2fb66fca547ca04cab083f93f00a9 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 3 Sep 2026 23:48:56 +0000 Subject: [PATCH] feat: add an inspect-only writing audit Add an inspect-only mode that reports findings without rewriting. The audit quotes each excerpt with its pattern number, explains why the match is contextual, and labels it clear, possible, or keep. A claim ledger lists rankings, qualifiers, numbers, names, dates, quotations, links, and simultaneity statements a rewrite must keep. The audit never scores the text or claims it is AI-generated. Mirror the mode in the README, route inspect intent in the skill description and OpenAI metadata, extend package validation to keep mode names and terms synchronized, and bump the version to 2.12.0. See #212, #229, #250. Co-authored-by: Matt Van Horn --- .claude-plugin/plugin.json | 2 +- README.md | 17 +++++++++++++++++ SKILL.md | 25 +++++++++++++++++++++++-- agents/openai.yaml | 4 ++-- scripts/validate-package.py | 21 +++++++++++++++++++++ 5 files changed, 64 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6ca35e92..5bb858b5 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": "2.11.2", + "version": "2.12.0", "author": { "name": "blader", "url": "https://github.com/blader" diff --git a/README.md b/README.md index aea9a0b4..494b4cce 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,22 @@ To rewrite a file, give Humanizer its path: Humanize the prose in docs/launch-post.md ``` +### Inspect-only mode + +Ask for an audit when you want findings instead of a rewrite: + +``` +Audit this text for AI patterns without rewriting it: [your text] +``` + +Humanizer returns a one-sentence assessment, a findings table, a claim ledger of details a rewrite must keep (rankings, qualifiers, numbers, names, dates, quotations, links, and simultaneity), and a short rewrite brief ordered by impact. It rewrites nothing and changes no file. It never gives a detector score or claims the text is AI-generated. + +Each finding quotes the source, names a pattern number, and carries a confidence label: `clear` (an edit would help), `possible` (the writer should decide), or `keep` (a false-positive rule protects it). For example: + +| Excerpt | Pattern | Why it matches | Confidence | +|---|---|---|---| +| "stands as a vibrant testament" | 1, 4 | Inflated legacy claim with sales tone in factual prose | clear | + ### Match your voice If you want the rewrite to sound more like you, include a sample: @@ -154,6 +170,7 @@ Humanizer follows the sample's rhythm, word choice, punctuation, and deliberate
Show release notes +- **2.12.0** - Added inspect-only mode: an audit that quotes each finding with its pattern number and a `clear`, `possible`, or `keep` confidence label, lists the claims a rewrite must keep, and rewrites nothing (see #212, #229, #250). 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. - **2.11.1** - Added a Claude Desktop-ready release package with one regular `humanizer/SKILL.md` file. GitHub's source archive still keeps the plugin symlink (fixes #224). No change to the 35 patterns. - **2.11.0** - Rewrote all repo guidance, descriptions, checks, and skill instructions in Plain Language. Kept all 35 patterns and their behavior. diff --git a/SKILL.md b/SKILL.md index c9c22422..68c60283 100644 --- a/SKILL.md +++ b/SKILL.md @@ -4,10 +4,12 @@ description: | Rewrite AI-sounding text so it reads naturally without changing what it says. Use when editing or reviewing prose for inflated claims, sales language, vague sources, repetitive structure, stock AI words, passive - voice, filler, or chatbot artifacts. Based on Wikipedia's "Signs of AI writing." + voice, filler, or chatbot artifacts. When the user asks for an audit, a review + for AI patterns, or what you would change without rewriting, report findings + instead of returning a rewrite. Based on Wikipedia's "Signs of AI writing." license: MIT metadata: - version: "2.11.2" + version: "2.12.0" --- # Humanizer: remove AI writing patterns @@ -437,6 +439,25 @@ These details often carry the writer's voice. Keep them unless they hurt the mea **Embedded mode.** When another task uses this skill for a pull request, commit message, or document, return only the final text. +**Inspect-only mode.** When the user asks for an audit instead of a rewrite, with requests such as "audit this text," "review this for AI patterns," or "show what you would change without rewriting," return the audit below. Do not use this mode for a plain rewrite or review request; the user must ask to see findings without a rewrite. + +## Inspect-only mode + +Run the same pattern check you would run before a rewrite, then stop. Return no rewritten prose and change no file. Apply every false-positive rule. Leave quotations, examples, code, proper names, and deliberate voice alone. Never give a detector score, a probability, or a verdict that the text is AI-generated. The audit describes patterns, not authorship. + +Return these four parts: + +1. **Assessment.** One sentence on how the text reads and how much editing it needs. Do not classify who or what wrote it. +2. **Findings table.** One row per finding: the exact excerpt quoted from the source, the matching pattern number, why the match is contextual rather than a banned word, and a confidence label. +3. **Claim ledger.** The meaning-sensitive language a future rewrite must keep: rankings and superlatives, qualifiers, numbers, names, dates, quotations, links, and statements that things happened at the same time. +4. **Rewrite brief.** A short numbered list of the edits you would make, highest impact first. Describe each edit without writing the new sentence. + +Use exactly three confidence labels: + +- `clear`: the pattern applies and an edit would help. +- `possible`: the pattern may apply; the writer should decide. +- `keep`: the text resembles a pattern but a false-positive rule protects it. + ## Rewrite process 1. Read the source and mark each AI pattern. diff --git a/agents/openai.yaml b/agents/openai.yaml index 16df2a8e..f0c621d9 100644 --- a/agents/openai.yaml +++ b/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Humanizer" - short_description: "Make AI-written text sound like the writer" - default_prompt: "Use $humanizer to rewrite this text in my voice without changing its facts." + short_description: "Make AI-written text sound like the writer, or audit it without rewriting" + default_prompt: "Use $humanizer to rewrite this text in my voice without changing its facts. If I ask for an audit, report findings without rewriting." diff --git a/scripts/validate-package.py b/scripts/validate-package.py index 30f07797..209f352d 100755 --- a/scripts/validate-package.py +++ b/scripts/validate-package.py @@ -82,6 +82,27 @@ def require_match(match: re.Match[str] | None, message: str) -> re.Match[str]: if readme_numbers != set(range(1, 36)): raise SystemExit("List patterns 1 through 35 in the README table") +return_modes = ( + "**Pasted text (default).**", + "**File mode.**", + "**Embedded mode.**", + "**Inspect-only mode.**", +) +missing_modes = [mode for mode in return_modes if mode not in SKILL] +if missing_modes: + raise SystemExit( + "Add the missing return modes to SKILL.md: " + ", ".join(missing_modes) + ) + +inspect_terms = ("Inspect-only mode", "`clear`", "`possible`", "`keep`") +for file_name, text in (("SKILL.md", SKILL), ("README.md", README)): + missing_terms = [term for term in inspect_terms if term not in text] + if missing_terms: + raise SystemExit( + f"Add the missing inspect-only terms to {file_name}: " + + ", ".join(missing_terms) + ) + if len(SKILL.splitlines()) > 500: raise SystemExit("Keep SKILL.md at 500 lines or fewer")