From dbfc74f2a54ca83c586a8da76c7c268d34db2562 Mon Sep 17 00:00:00 2001 From: Raymond Ware Date: Mon, 26 Oct 2026 10:54:01 -0700 Subject: [PATCH 1/2] fix: preserve clarity when tightening prose Keep readers from reconstructing missing grammar and connections after a style edit. Check explanatory passages without changing meaning, voice, or the existing workflow. --- .claude-plugin/marketplace.json | 4 +-- .claude-plugin/plugin.json | 2 +- VERSIONING.md | 2 ++ agents/voice-implementer.md | 4 +++ skills/humanize/SKILL.md | 3 +++ skills/humanize/references/examples.md | 28 +++++++++++++++++++ skills/scribe/SKILL.md | 5 ++-- skills/scribe/references/reader-clarity.md | 31 ++++++++++++++++++++++ tools/validate_plugin.py | 2 +- 9 files changed, 75 insertions(+), 6 deletions(-) create mode 100644 skills/scribe/references/reader-clarity.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8073c66..0a675ee 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Voice-preserving prose editing and a longform writing harness", - "version": "1.1.0" + "version": "1.1.1" }, "plugins": [ { "name": "scribe", "source": "./", "description": "Focused humanize editing plus a multi-agent longform harness. Preserves voice and meaning in existing prose, with five writer personas and parallel critics for pipeline workflows.", - "version": "1.1.0", + "version": "1.1.1", "author": { "name": "raymondware" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5a10b13..b2de5a4 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "scribe", - "version": "1.1.0", + "version": "1.1.1", "description": "Focused humanize editing plus a multi-agent longform harness. Preserves voice and meaning in existing prose, with five writer personas and parallel critics for pipeline workflows.", "author": { "name": "raymondware" diff --git a/VERSIONING.md b/VERSIONING.md index 712c105..75752dc 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -4,6 +4,8 @@ Scribe follows semantic versioning. ## Current +v1.1.1 - Refines humanize and voice revision to unpack compressed prose and check reader understanding while preserving meaning and genre. + v1.1.0 - Adds the focused `/scribe:humanize` skill, original editing examples, and skill packaging validation. Existing pipeline commands keep their behavior. v1.0.0 -- Initial public release. 5 personas, anti-pattern library, conductor + 11 agents wired. diff --git a/agents/voice-implementer.md b/agents/voice-implementer.md index b858fe7..d9cfe0d 100644 --- a/agents/voice-implementer.md +++ b/agents/voice-implementer.md @@ -47,6 +47,10 @@ Confirm at least one short paragraph (1-2 sentences) per page. Confirm no run of Read the whole passage end-to-end. Does it sound like one person wrote it? If parts drift toward a different register, pull them back. Does it sound like the persona's exemplars? Adjust until it does. +### Pass 6: Reader understanding (explanatory prose) + +For passages that explain a real subject, or when the brief requests a clarity check, read `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/reader-clarity.md`. Repair shorthand and missing connections using the supplied material. Keep the existing meaning, word-count limits, and paragraph order. Preserve complete reasoning when adjusting cadence to a rhythm target. This is an editing check, not another critic round; keep the prose-only output. + ## Hard Rules - Do not change the meaning of any paragraph. You are revising for voice and rhythm, not content. diff --git a/skills/humanize/SKILL.md b/skills/humanize/SKILL.md index 7f8046d..fb8b2b4 100644 --- a/skills/humanize/SKILL.md +++ b/skills/humanize/SKILL.md @@ -36,6 +36,7 @@ Look for a mismatch between what a passage says and how it says it. Start with p | Spends several sentences announcing an ordinary point | Bring the actual point forward and remove redundant setup | Keep context the reader needs to understand it | | Makes a claim sound larger than the supplied evidence | Remove the promotional or grand wording | Keep the claim's scope and any supported consequence | | Uses abstraction where the source already gives an action | Use the supplied actor and action | If the actor is unknown, passive voice can be accurate | +| Packs actions and conditions into shorthand | Restore complete clauses and the connections the text supplies | Keep identifiers exact; do not assume an unexplained symbol establishes cause or order | | Repeats the same rhetorical move across paragraphs | Rebuild the affected passage around its sequence of ideas | Repetition can also carry character, emphasis, or a technical distinction | | Replaces individual voice with generic smoothness | Restore the writer's recognizable choices | Do not invent personality, experience, or conviction | @@ -43,6 +44,8 @@ For Scribe's named patterns, consult `${CLAUDE_PLUGIN_ROOT}/anti-patterns/manife A familiar word, a three-item list, a semicolon, or an evenly paced paragraph can be exactly right. Keep domain terms and consistent names for the same thing. Do not cycle synonyms, delete every adverb, impose sentence-length quotas, or convert useful lists into prose just to vary the surface. +For a clarity edit, or a passage explaining something unfamiliar to its audience, read `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/reader-clarity.md`. A few extra words can make a compressed sentence easier to follow. Keep deliberate ambiguity and character speech when they belong to the work. + ## Make the edit earn its place Change the smallest span that solves the problem. Rewrite a paragraph when local substitutions leave its reasoning stiff. Reorder information within the passage if that clarifies the existing point; preserve procedural order and dependencies. Do not expand the argument or rebuild the document around a new thesis. diff --git a/skills/humanize/references/examples.md b/skills/humanize/references/examples.md index 5510ed4..79550d6 100644 --- a/skills/humanize/references/examples.md +++ b/skills/humanize/references/examples.md @@ -86,6 +86,34 @@ Possible edit: The setting, link destination, ordering, and restart requirement stay intact. In a file, frontmatter, code samples, and template expressions would also stay intact. A list of actual setup steps should remain a list. +## Unpack a production note + +Request: Make this note easier to follow. + +Before: + +> Chapter-template replacement removed page numbers; footer restore required before proof export. + +After: + +> Replacing the chapter template removed the page numbers. Restore the footer before exporting the proof. + +The edit gives the second clause a verb and makes the sequence readable. The template change, missing page numbers, and required order stay the same. No extra production step is added. + +## Explain a supplied term for a new audience + +Request: Make this explanation accessible to a general reader. Here, albedo means the fraction of sunlight a surface reflects. + +Before: + +> Ice loss lowers albedo. The surface absorbs more sunlight as a result. + +After: + +> Ice loss reduces albedo, the fraction of sunlight a surface reflects. The surface then absorbs more sunlight. + +The writer supplied the definition, and the passage already stated the relationship. The edit places that information together while keeping the technical term. An explanation for specialists might need no definition. + ## Community influences The skill's workflow, wording, and examples are original to Scribe. These community projects informed the design: diff --git a/skills/scribe/SKILL.md b/skills/scribe/SKILL.md index 6eea86c..ec121ff 100644 --- a/skills/scribe/SKILL.md +++ b/skills/scribe/SKILL.md @@ -1,10 +1,10 @@ --- name: scribe -version: 1.1.0 +version: 1.1.1 description: Multi-agent writing harness for longform authors. Catches AI-default writing patterns (delve, tapestry, em-dash overuse, hedging openers, three-word lists, negative/positive restatement, conclusion-restating) before they ship. Five writer personas (literary fiction, popular nonfiction, technical writing, memoir, business book), persona-specific rhythm and voice rules, anti-pattern rotation per run with audit log, multi-critic synthesis. Built for authors, essayists, ghostwriters, and editors. --- -# Scribe v1.1.0 +# Scribe v1.1.1 Multi-agent writing harness for authors who care about voice. @@ -181,6 +181,7 @@ Append-only audit log lives at `${CLAUDE_PLUGIN_ROOT}/state/draws.jsonl`. Every |---|---| | `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/exemplars.md` | Author/book exemplars per persona | | `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/rhythm-tokens.md` | Cross-persona rhythm targets and vocabulary | +| `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/reader-clarity.md` | Clarity checks for compressed and explanatory prose | | `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/orchestration/pipeline.md` | Pipeline state machine | | `${CLAUDE_PLUGIN_ROOT}/skills/scribe/references/orchestration/quality-gates.md` | Gate criteria | diff --git a/skills/scribe/references/reader-clarity.md b/skills/scribe/references/reader-clarity.md new file mode 100644 index 0000000..c5db161 --- /dev/null +++ b/skills/scribe/references/reader-clarity.md @@ -0,0 +1,31 @@ +# Reader clarity + +Use this during an edit of explanatory prose or when the brief asks for a check of reader understanding. It fits inside the existing editing pass. It does not require another agent, a score, or a report. + +## Give the sentence enough room + +A short passage can ask the reader to do too much reconstruction. Look for clipped clauses, dense strings of nouns, unexplained abbreviations, and symbols standing in for relationships. Restore the words needed to tell who acts, what changes, and when a condition applies. + +Keep each relationship as precise as the material allows. If it states a reason, make that reason legible. If it only places two events together, preserve that limit. Adding "because" or "therefore" can introduce a claim even when every noun stays the same. + +Keep a technical name that identifies the right thing. When the material supplies an explanation and the audience needs it, place that explanation near the name. Avoid replacing a precise term with a general word or defining vocabulary the intended reader already knows. + +Some longer sentences carry a comparison or dependency more clearly than several short ones. Adjust their rhythm without removing qualifications or scattering the reasoning. Additional words should clarify existing information. + +## Check what the reader can follow + +For an explanatory passage, briefly work through it with the stated audience in mind: + +- Describe its main claim in ordinary language, then check that the passage actually supports that reading. +- Follow the explanation from one sentence to the next. Locate any place where understanding depends on something present only in the brief or in the editor's head. +- For instructions, check that the reader can identify the action, its conditions, and any stated way to recognize completion. + +Repair a break using information already available: move a supplied explanation, make a reference explicit, or reconnect clauses. A missing detail remains missing until the writer supplies it. Do not manufacture a reason, definition, or benefit to make the account feel complete. + +Use this check in proportion to the passage. A novel can withhold a motive. Dialogue can be clipped. An essay can earn its argument gradually. Preserve those choices instead of forcing every piece to announce its conclusion immediately. + +## Check the effect of the edit + +Read the changed passage against its original meaning. Check whether a removed detail was limiting another statement, whether a simplified verb lost part of the action, or whether smoother wording changed uncertainty into a promise. Correct the wording rather than adding a new explanation around it. + +Keep this reasoning private unless the user asks for editorial notes. Stop when the passage carries its meaning clearly in the intended voice. diff --git a/tools/validate_plugin.py b/tools/validate_plugin.py index 1b18a3a..d3ae53b 100644 --- a/tools/validate_plugin.py +++ b/tools/validate_plugin.py @@ -42,7 +42,7 @@ def validate_plugin_manifests() -> None: if plugin.get("name") != "scribe": fail("plugin.json name must be scribe") - if plugin.get("version") != "1.1.0": + if plugin.get("version") != "1.1.1": fail("plugin.json version must stay aligned with release docs") if plugin.get("license") != "MIT": fail("plugin.json license must be MIT") From 66e1363a96c2c893b588eb2a3fabc521492cfbc3 Mon Sep 17 00:00:00 2001 From: Raymond Ware Date: Mon, 26 Oct 2026 14:25:11 -0700 Subject: [PATCH 2/2] docs: clarify Scribe commands and examples --- README.md | 56 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 76d4d79..639d153 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ Scribe is a Claude Code plugin for authors, essayists, and editors. It finds the /scribe:revise ``` -Paste a passage after `/scribe:revise`. Scribe returns the rewrite, a diff, and a 0-100 sameness score. +Paste a passage after `/scribe:revise`. Scribe returns the revised passage with before-and-after sameness scores on a 0-100 scale. -For a focused edit, use `/scribe:humanize` with a passage or file path. It keeps your voice and meaning, removes stiffness where needed, and returns the edited passage. It runs directly without the agent pipeline, pattern draw, audit log, or score. Already-effective prose can stay unchanged. +For a focused edit, use `/scribe:humanize` with a passage or file path. It removes stiffness while keeping your voice and meaning. For pasted text it returns just the edited passage; for a requested file edit it changes the prose in place. It skips the agent pipeline, pattern draw, audit log, and score, and it leaves prose that already works unchanged. ### Before @@ -21,14 +21,14 @@ For a focused edit, use `/scribe:humanize` with a passage or file path. It keeps | Flagged | Pattern | |---|---| | "In today's fast-paced world" | `in-todays-fast-paced-world` | -| "isn't about authority; it's about influence" | `negative-positive-restatement` | +| "isn't about authority; it's about influence" | `not-x-but-y-frame` | | "don't just manage teams, but inspire them" | `not-just-x-but-y-reflex` | | "empathy, clarity, and vision" | `tricolon-reflex` | | "leveraging", "unlock the full potential" | `marketing-verb` | | "It's important to note that" | `its-worth-noting-throat-clearing` | | "not a destination. It is a mindset." | `negative-positive-restatement` | -### After +### After (illustrative) @@ -40,7 +40,7 @@ For a focused edit, use `/scribe:humanize` with a passage or file path. It keeps AI-generated writing converges on the same cadence. "Delve into the tapestry of." "It's important to note that." "Not just X, but Y." "This is not X. It is Y." Em-dashes everywhere. Three-word lists. Conclusion paragraphs that restate the previous five. Hedging openers. -Scribe fixes this with persona-first generation and a sameness score that quantifies how close prose is to the AI default. +Scribe combines persona-specific writing rules with critic reviews of those habits. ## Installation @@ -51,11 +51,11 @@ Add the raymondware marketplace, then install Scribe: /plugin install scribe@raymondware ``` -Restart Claude Code and the `/scribe:*` commands are available. +After you restart Claude Code, the `/scribe:*` commands are available. ## Quick Start -```bash +```text # Generate a passage from scratch /scribe:write opening chapter for a popular nonfiction book about how cities forget their own histories @@ -65,6 +65,7 @@ Restart Claude Code and the `/scribe:*` commands are available. # De-AI an existing draft /scribe:differentiate +# (paste the draft) # Run only the anti-pattern selector (verifies rotation) /scribe:draw memoir essay about my year in Buenos Aires @@ -76,21 +77,21 @@ Restart Claude Code and the `/scribe:*` commands are available. |---|---| | `/scribe:humanize ` | Edit existing prose for naturalness while preserving voice, facts, and useful structure | | `/scribe:write ` | Full pipeline: persona detection, specialists, draft, review | -| `/scribe:audit` | Anti-pattern scan with sameness score against existing prose | -| `/scribe:revise` | Rewrite a passage against Scribe's standards, show diff | -| `/scribe:differentiate` | Identify AI writing tells and apply targeted fixes | -| `/scribe:diagnose` | Single-pass AI-ism detection, fast turnaround | -| `/scribe:compare ` | Side-by-side prose comparison with similarity score | -| `/scribe:plan ` | Writing specs only (voice, rhythm, structure) -- no draft | -| `/scribe:review` | Full review pass: critic ensemble, voice editor | -| `/scribe:research` | Scan writing communities for new anti-patterns | -| `/scribe:draw ` | Run the anti-pattern selector standalone (rotation verification) | +| `/scribe:audit` | Scan existing prose for anti-patterns and give it a sameness score, without rewriting it | +| `/scribe:revise` | Make targeted revisions against Scribe's standards and show before/after scores | +| `/scribe:differentiate` | Identify AI writing tells and apply heavier, structural fixes | +| `/scribe:diagnose` | Run the critics and group AI-ism findings without a score | +| `/scribe:compare [--persona ] [--mode before-after \| vs-exemplar]` | Compare two supplied passages using the same pattern subset and report their sameness scores | +| `/scribe:plan ` | Writing specs only (voice, rhythm, structure), no draft | +| `/scribe:review` | Most thorough audit: every critic, including pacing, and a larger pattern subset | +| `/scribe:research` | Scan writing communities for new anti-patterns and propose them in a pull request | +| `/scribe:draw ` | Run the anti-pattern selector on its own (rotation verification) | ## How It Works ### 1. Persona Detection -Scribe picks a persona from your description, then loads that persona's rules for voice, rhythm, vocabulary, and structure. Five personas: +Scribe picks a persona from your description, then loads that persona's rules for voice, rhythm, vocabulary, and structure. There are five personas: | Persona | For | |---|---| @@ -102,15 +103,15 @@ Scribe picks a persona from your description, then loads that persona's rules fo ### 2. Variation Rule -Every pipeline run picks a different subset of anti-patterns. Scribe reads the audit log (`state/draws.jsonl`) and excludes the previous run's subset. Two runs on the same prompt produce different critiques. The focused `/scribe:humanize` skill works outside this pipeline. +Each pipeline run checks a different subset of anti-patterns. Scribe reads the audit log (`state/draws.jsonl`) and leaves out the previous run's subset, except for three negative-parallelism patterns that are included every time. So two runs on the same prompt are critiqued against different subsets. The focused `/scribe:humanize` skill doesn't use this rotation. ### 3. Parallel Critics + Synthesizer -Five critics run in parallel (rhythm, voice, cliche, AI-ism, pacing). The synthesizer merges their output, removes duplicates, and computes a consensus sameness score. +Rhythm, voice, cliche, and AI-ism critics run in parallel. A pacing critic joins for chapters and essays and always runs for `/scribe:review`. The synthesizer merges their output, removes duplicates, and computes a consensus sameness score. ### 4. The Sameness Score -Every draft gets a 0-100 score on AI-default similarity: +Scored commands rate prose from 0 to 100 by how closely it resembles AI-default writing. Lower is better: | Score | Meaning | |---|---| @@ -120,15 +121,17 @@ Every draft gets a 0-100 score on AI-default similarity: | 61-80 | Default AI prose. Multiple tells per page. | | 81-100 | Unedited AI output. Do not ship. | +The score is a craft signal, not an AI-authorship detector. + ## Anti-Pattern Library -Scribe ships with anti-patterns across three files: +Scribe ships with 31 anti-patterns across three files: | File | Patterns | |---|---| -| `anti-patterns/language.md` | Delve/tapestry/realm vocabulary, tricolon reflex, hedge stacking, marketing verbs, em-dash overuse, self-descriptors, negative/positive restatement, filler intensifiers | -| `anti-patterns/rhetoric.md` | Universal aphorisms, "not just X but Y" frames, throat-clearing openers, flashlight-hedging adjectives | -| `anti-patterns/structure.md` | Conclusion-restating, predictable section sequence, thesis-delay syndrome | +| `anti-patterns/language.md` | Stock AI vocabulary, tricolons, hedge stacking, marketing verbs, em-dash overuse, self-descriptors, universal aphorisms, contrast formulas, filler intensifiers, and throat-clearing | +| `anti-patterns/rhetoric.md` | Generic openers, universalizing claims, false dichotomies, rhetorical questions, pseudo-reveals, repeated twists, and stock closing lines | +| `anti-patterns/structure.md` | Uniform paragraphs, recap openings, repeated conclusions, predictable section sequences, decorative lists, and anecdote montages | ## Agent Team @@ -138,12 +141,15 @@ Scribe ships with anti-patterns across three files: ### Drafting (Sonnet) `draft-implementer` `voice-implementer` -### Critics (parallel ensemble) +### Critics (parallel ensemble; Haiku, with `voice-critic` on Opus) `rhythm-critic` `voice-critic` `cliche-detector` `ai-ism-critic` `pacing-critic` ### Orchestration `conductor` `critique-synthesizer` (Opus), `anti-pattern-selector` (Sonnet) +### Research and Evaluation (Sonnet) +`research-scout` `external-judge` `cross-persona-audit` + ## Contributing See `CLAUDE.md` for the contributor guide.