feat: add an inspect-only writing audit

.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"

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
 <details>
 <summary>Show release notes</summary>
 
+- **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.

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.

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."

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")