Plainspoken

Plainspoken: plain-language + humanizer pass

You are editing copy so it reads like a careful person wrote it for a general audience. This skill layers a de-jargoning process and the no-ai-slop pattern set on top of the humanizer guide. All three must be applied.

Two modes

Edit (default). The user wants a draft fixed. Make the minimum effective edit, then return the edited work and a short What changed section.

Detect. The user asks whether something reads as AI, or asks to audit, scan, or flag a draft without rewriting it. Name each pattern from this skill that appears, quote the line, and give the fix in a few words. Do not rewrite, do not score the draft, and do not guess whether AI wrote it. Detectors guess; named patterns are evidence the user can check for themselves. Offer to run the edit afterward.

Step 1 — Know the job, and find the voice before you touch anything

Before structure or word choice, know what the piece is trying to do and who it is for. If the audience or format is unclear, ask one question: who is this for and where will it be published? If the goal is unclear, ask what the reader should think, feel, or do after reading it.

Then read the whole draft and note 3-5 voice signals to protect: vocabulary, cadence, bluntness, humor, uncertainty, digressions, level of polish. Keep that note internal. This step exists because every other step in this skill is subtractive, and subtractive editing applied without a voice model produces evenly-tidy prose that sounds like nobody. A rough draft with a real voice should still sound like the same person afterward.

If references/voice.md exists in this skill's directory, read it now. It records this writer's standing voice exceptions: places where a pattern rule and their voice disagreed and the voice won. Those exceptions override the pattern rules below. (See references/eval.md for the founding example.)

• Make the minimum effective edit. Fix the patterns below. Leave strong human sentences alone. Cutting should be proportional to the actual slop.
• Do not make every paragraph equally tidy. Uneven polish is often the writer, not a defect.
• Preserve useful edge. Strong opinions, blunt language, humor, profanity, self-interruptions, and honest admissions stay when they belong to the writer. Do not swap them for safer or more professional wording.
• Keep structure and detours unless they are hurting the piece. If you reorganize, say why in What changed.
• Keep the writer's meaning. Never invent claims, examples, stats, quotes, or opinions. If something is unclear, ask.
• Lead with the point when the setup adds nothing, but keep a personal aside, story, or admission when it creates context, tension, or character. Front-load only where it improves clarity; do not force every section into the same point-detail-background shape.

Step 2 — Read the humanizer guide

Read references/humanizer.md in this skill's directory (vendored from https://github.com/blader/humanizer, MIT license) and apply ALL of its patterns. Treat the following as hard rules, not preferences:

1. No em dashes or en dashes. Ever. Replace with a period, comma, colon, or parentheses, or restructure. Date/number ranges become hyphens ("1919-1969") or words ("5 to 4 vote"). Before finishing, grep the output for — and –; any hit outside a direct quotation means you are not done.
2. No negative parallelisms. Kill every "Not X. But Y.", "not just X, it's Y", "X is not a tool but a mirror", and tailing-negation fragments ("no guessing", "not a press release"). State the positive claim directly.
3. No rule-of-three cadence, no manufactured punchlines or staccato drama, no aphorism formulas ("X is the Y of Z", "Process is destiny", "Scale is strategy"). Replace the formula with the concrete claim it gestures at.
4. No compressed-parallel ring headlines: "[big number/span], one [noun]" or "[plural], one [singular]" used as a punchy title or heading (the "Two centuries, one record." pattern). It reads as a generated tagline because it states a scope and then rhymes a random noun against it instead of making a claim. Replace with a sentence that says the actual point.
   • "Two centuries, one record." → "The failures and the fixes are both on the record."
   • "Forty cities, one lesson." → "Every city in this study hit the same wall: money without a plan to spend it."
   • "A hundred voices, one demand." → say what the demand was. The test: does the heading survive being read aloud to someone who wasn't already nodding along? If it only sounds good because of the rhythm, cut it.

Step 3 — The de-jargoning pass (this skill's additions)

Hunt for these six families. Each has real before/after examples from a civic website edit where this process was developed. Families A-E are word- and phrase-level fixes; family F is a deeper structural pass over compressed ideas, not just individual words, and is usually the one that takes a "quick edit" to a genuine rewrite. Do not skip F because A-E already look clean.

A. Absolute / overly-authoritative claims

Sweeping declaratives that outrun the evidence. Soften to what the record actually supports; attribute judgments to someone.

• "eligibility decides everything downstream" → "eligibility shapes everything that follows"
• "The vote that defined everything" → "The eligibility vote"
• "Dedicated sin-tax streams underperformed everywhere." → "Taxes earmarked from cannabis and similar sources fell short in every city that tried them."
• "Every government commission missed its first deadline." → "Nearly every government commission missed its first deadline."
• "The city must choose its own center of gravity." → "The city will need to choose its own starting point."
• "Unflinching is the only honest speed." → cut; say what the section actually contains.

The rule: facts stay declarative ("The city closed the crossing in 1962"), judgments and predictions get attributed or qualified ("Advocates argue...", "The record suggests...", "tended to...").

B. Coined labels and concept abbreviations

Invented shorthand the reader must decode: "the civil-society model", "the durability menu", "## The machine", "the structural opposite", "severability and sequencing", "the advocacy bench", "north star".

• "## The machine" → "## How it was staffed"
• "the civil-society model. When the legislature stalled..." → "when the legislature stalled, a nonprofit stepped in."
• "Verification, the machinery under every model" → "Verification, which every model depends on"
• "The case for: severability." → "The case for: if one track is struck down, the others still stand."
• "the shared grammar of American commissions" → "the common reference point for American commissions"
• "Rank the goals that should function as the project's north star." → "Rank the goals that should guide the project's work."

If a label is a real proper noun (a program name, a court case, a defined term of art the audience knows), keep it. The test: would a smart reader outside your field know what it means without the label being explained?

C. Techie / software / business vocabulary

Words that make civic or general-audience copy sound like a startup standup: shipped, ship it, anti-pattern, proven out, architecture (metaphorical), pipeline (metaphorical), leverage (verb), surface (verb), bandwidth, scale (verb, casual), workhorse, spine, stack, de facto, MVP, roadmap.

• "consultant-dependent processes stalled; staffed ones shipped" → "...tended to stall. The ones with paid staff kept moving."
• "San Francisco demonstrated the anti-pattern" → "San Francisco showed what not to do"
• "Four method families have proven out." → "Four approaches have a track record."
• "a unified repair architecture" → "a single unified repair program"
• "the quiet workhorse" → "the steady, reliable source"
• "staff spine" → "a staff core"
• "the county's de facto model" → "the model the county effectively used"

D. Unexplained abbreviations

Spell out any abbreviation a general reader would not know on first use: "RETT" → "real-estate transfer tax"; "GO-bond" → "general-obligation bonds". Widely-known ones (DOJ, HUD, NAACP) and ones the document itself defines are fine.

E. Repeated metaphor systems

A metaphor used once is voice; a metaphor used as load-bearing vocabulary across a document ("the ledger", "the signal", "the record" as brand-speak) makes readers translate. Keep at most the one or two instances where it is a deliberate motif; convert the rest to the plain word.

Careful: distinguish literal from metaphorical. "Tax ledgers" in an archive are real objects and must stay; "the extraction ledger" as a name for a methodology becomes "the extraction accounting".

F. Concept-unpacking (go beyond word swaps)

Families A-E fix words and phrases. This one fixes compressed ideas: places where the reader has to do inference work the writer skipped. This is the deepest layer of the pass and the one most often missed by a quick find-and- replace edit. Look for:

• Label-led list items that need decoding. A bolded or short label followed by a colon, where the label itself is jargon, forces the reader to guess what it means before reading the explanation. Expand the label into the first clause of a real sentence instead.
  • "Consultant dependence. The first project-management consultant resigned..." → "The commission depended on outside consultants. The first project-management consultant resigned..."
  • "Vehicle design. The pilot fund's $6.4M sat in public accounts..." → "Where the money sits. The pilot fund's $6.4M sat in ordinary public accounts..."
• Legal, financial, or technical terms used without a definition. The first time a term of art appears, define it in the same sentence, briefly, then use it freely after that.
  • "the government must receive real consideration" → "the government must receive something real in return for what it gives (what contract law calls consideration)"
  • "courts construe local power narrowly under home rule" → "cities in the state have only the powers the state grants them (called home rule), and courts read those powers narrowly"
  • "a race proxy" → "a stand-in for race"
• Formulas and named methodologies stated but not explained. If a document gives an equation, an acronym-model, or a "signature method," follow it immediately with a plain-English paraphrase of what it actually does.
  • "FV = PV(1 + r)^n" → keep the formula, then add: "In plain terms: the starting amount grows by the same percentage each year, and the growth itself starts growing, the way compound interest does."
• Coined section headings that name a metaphor instead of the content. "## The machine", "## The vehicle", "## The counter-history" tell the reader there's a bit to decode before they know what's in the section. Rename to what the section is actually about.
  • "## The listening infrastructure" → "## How residents were heard"
  • "## Choosing the pen" → "## Who does the research"

The test for this whole family: read each sentence and ask "would someone need to have already been thinking like the writer to parse this on first read?" If yes, unpack it, even if no single word in it is jargon.

Step 4 — AI-slop patterns (from petergyang/no-ai-slop)

Families A-F above catch jargon and compression. These catch the tics that make prose read as machine-written even when every word is plain. Vendored from https://github.com/petergyang/no-ai-slop; the overlapping patterns (em dashes, negative parallelism, rule-of-three, coined labels, techie vocabulary) are already handled above and are not repeated here.

Words to cut

Banned outright: delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, this is huge, this changes everything, tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving.

Often-empty adverbs: just, literally, honestly, simply, actually, truly, fundamentally, importantly, crucially, inherently, inevitably. Cut when they add nothing. Keep them when they carry emphasis, uncertainty, contrast, or the writer's spoken rhythm — this carve-out matters, and a blanket sweep of this list will strip real meaning. "Governments have actually done this" answers a doubt; "actually restricts direct payments" answers a myth. Both stay.

Often-empty phrases: it's worth noting, it's important to note, at the end of the day, when it comes to, at its core, in today's world, in the age of, in the world of, the reality is, the truth is, in terms of, with regard to, in order to, going forward, in this article, let's dive in. Cut when they delay the point; keep the occasional one that is part of the writer's voice.

Patterns to cut

Colon reveals. A noun phrase, a colon, then a lowercase dramatic reveal: "The detail that makes it work: a separate agent grades it." Rewrite as a plain sentence. Colons are fine for lists, labels, quotes, and appositives ("The committee begins with an unusual advantage: the archive is already digitized"). They are not fine as manufactured drama. Sentence case after a colon unless grammar, a proper noun, a title, or code requires otherwise.

• "The practical consequence: direct payments are barred." → "In practice, direct payments are barred."
• "The risk: without funding, pilots end." → "Without funding, pilots end."

Weasel attribution. "Experts agree," "studies show," "many argue," "widely regarded as," "observers read it as," "analysts consider." Name the source or cut the claim. Never invent a crowd. If the user has no source, ask rather than manufacture one.

Reconciling this with family A: family A says attribute judgments rather than stating them as fact, and that still holds — but attribution means a named, checkable source. When you have none, either own the judgment in the document's own voice ("a warning about tying a commission's existence to one executive") or mark it as the document's reading ("The record suggests"). "Observers read it as" is not attribution; it is a crowd you made up.

Faux-insight setups. "This is the part most people skip," "what most people get wrong," "here's what nobody tells you," "the part everyone misses." These flatter the writer as the lone expert. Cut the setup; let the claim stand alone.

Throat-clearing openers. "Here's the thing," "here's what I mean," "let me be clear," "I'll be honest," "the uncomfortable truth is."

Rhetorical setups. "What if I told you...", "Think about it:", "Plot twist:", and self-answered "Question? Answer." pairs. A genuine question that frames a section is fine; a question posed only to be immediately answered by the same writer is not.

Superficial analysis. Trailing -ing clauses that pretend to explain significance: "highlighting," "underscoring," "reflecting," "showcasing," "signaling," "demonstrating." Replace with the actual consequence.

• "adds file search, highlighting the team's commitment to workflows" → "adds file search, so users can find old drafts without leaving the editor"

Importance puffery. "Stands as a testament," "marks a pivotal moment," "plays a vital role," "solidifies its position," "underscores its significance." State the fact and let the reader judge whether it matters.

Fake-strong verbs. Prefer "is" and "has" when they are clearer than a dressed-up verb. "The app serves as a centralized hub for sponsor management" → "The app tracks sponsors, drafts, due dates, and approvals in one place."

Make verbs do the work. "Made a decision" → "decided." "Has the ability to" → "can." "Provides support for" → "supports." The same goes for nominalized gerunds used as rhetorical nouns: "the noticing costs you respect" → "that costs you respect."

Active voice, with human subjects. "The team shipped it Tuesday" beats "the decision emerged." Never let inanimate things do human verbs — no "the ground remembers," "the data tells us," "the market decided." Name who did the thing.

Synonym cycling. If the clear word is right, repeat it. Do not rotate terms for variety: "The agent reviews the draft. The assistant scores the piece. The tool suggests fixes" → "The agent reviews the draft, scores it, and suggests fixes."

Negative listing. "Not a X. Not a Y. A Z." Just say Z.

Robotic rhythm. Repeated sentence shapes, identical paragraph structures, stacked punchy fragments. Vary shape only when it helps the point.

Fake-profound kickers. The final "deep" line that turns the point into a metaphor, aphorism, or mic-drop. Delete it. Do not rewrite it into a better metaphor, and do not preserve its rhythm. End on the clearest concrete sentence already in the draft; if the ending needs closure, add a plain takeaway or next action.

• "If this work has sacred ground, this meeting is it. Be in the room." → "Be in the room."

Summary-recap endings. "In conclusion," "Ultimately," "Overall," or a final paragraph restating the piece. The reader was just there.

Formatting slop. Emoji in headings, bold sprinkled mid-sentence for emphasis, bullet lists where two sentences of prose read better, headers over two-sentence sections. Format follows content; it does not decorate it.

Be concrete (the one positive instruction)

Everything above removes. This one adds. Abstraction is where writing goes to die, so push toward names, numbers, dates, mechanisms, and examples — and protect the specific fact when you find one. Never smooth a useful detail into generic importance.

• "The integration improved efficiency" → "The integration cut deploy time from 40 minutes to 4."
• "The tool significantly improves engineering productivity" → "The tool cut review time from 30 minutes to 8."

Step 5 — Front-door copy (marketing surfaces)

These patterns live at the argument level, not the sentence level, and they show up on marketing surfaces: READMEs, landing pages, launch posts, About pages, app-store copy. A sentence-level pass misses them because every sentence looks clean. They were mined from a real edit (the owner of this skill editing its own README), so each has a real before/after.

• Pitch stitched into the diagnosis. The problem statement ends with a clause selling the product. State the problem; the product gets its own paragraph.
  • "Publishing the model's default voice is the problem, and that part is fixable with an editing pass that knows exactly what to look for." → "Publishing the model's default voice is the problem."
• Attacking the alternative. Foil-bashing is the argument-scale version of negative parallelism. Say what yours does; drop the foil.
  • "It will never tell you '87% AI.' Detectors guess and get people falsely accused; named patterns are evidence you can check yourself." → "It names patterns and quotes lines, evidence you can check yourself."
• Proof pileups. Stacked anecdotes, statistics, and examples performing thoroughness. Keep the one beat the reader has personally lived; link the rest if it matters.
• Rationale before behavior. A mini-theory justifying each feature before saying what it does. State the behavior; the why lives in docs.
  • "Every rule is subtractive, and subtractive editing without a voice model produces evenly tidy prose that sounds like nobody. So the skill starts by reading the whole draft..." → "The skill starts by reading the whole draft and noting the writer's voice."
• Feature self-grading. Rating your own feature's importance is importance-puffery pointed at yourself. Show the feature; the reader grades it.
  • "A what-NOT-to-touch list is half of what makes an editing skill safe to run on real work." → keep the list, cut the appraisal.
• Origin story up front. Provenance claims and war stories belong in docs or a history page. The front door states the conclusion and links.
• Bold lead-ins as emphasis. Bolded mini-headlines opening each paragraph in a pitch section. Bold lead-ins are fine as labels for parallel options a reader picks between (install paths, modes); as paragraph hype they are formatting slop. The test: is the reader choosing between these, or being sold?
• Illustrating the obvious. An example decorating a claim nobody doubts. "Be concrete" applies to claims that need evidence, so cut the illustration where the claim is already believed.
  • "It asks who the piece is for, because 'plain' for a law review and 'plain' for a neighborhood newsletter are different jobs." → "It asks who the writing is intended for."
• Motif callbacks in short copy. The metaphor budget scales with length. In a README or landing page it is zero, even when the metaphor was set up two sentences earlier.
  • "...so your writing doesn't join the wallpaper." → "...so your writing doesn't join that list."
• Writerly determiners. The one sentence-level pattern in this family, because it clusters on the same surfaces. "The" gets used for things never introduced: the you-know-the-one example ("the cafe caption that says..."), the singular-generic subject ("the label-led list item forces the reader to..."), and nouns the reader owns ("a professor discounts the paper"). Pick the determiner by ownership: the reader's things take "your"; invented examples take "a" or a bare plural; "the" is for a thing already introduced or genuinely unique.
  • "A professor discounts the paper." → "A professor discounts your paper."
  • "the cafe caption that says..." → "a cafe caption that says..."
  • "the label-led list item that forces the reader to decode jargon" → "label-led list items that force the reader to decode jargon"

Step 6 — Language dignity rules

• Person-first language for people: "enslaved people" or "people who were enslaved", never "the enslaved". Same pattern for other groups ("people experiencing homelessness" over "the homeless") where the document's register calls for care.
• No leading "The X" title pattern across a nav or article set ("The Survey", "The Study", "The Signal" reads like Seinfeld episode titles). Titles and links drop the article: "Survey", "Study", "Results".
• Don't claim comprehensiveness the content doesn't have ("Every major effort, one map"). If an authoritative external source exists, link it and scope your own claim honestly.

What NOT to touch

• Direct quotations, titles of works, legal case names, statute citations, proper nouns, and historical notation reproduced from a source (including dashes inside quoted material).
• Precise technical terms in a document FOR a technical audience. This skill is about audience fit, not dumbing down.
• Facts, figures, dates, names, citations, and links. Rewrite the prose around them; never alter them.
• Documented history stated plainly. Softening applies to judgments, not to atrocities with citations. "At least 25 people were killed" stays declarative.
• Adverbs and phrases from the Step 4 lists that carry contrast, emphasis, or uncertainty, and any that sit inside a quotation or inside a claim the piece is rebutting. Check each hit; never sweep those lists blind.
• Stored keys and values: database ids, option ids, enum values, saved form values. Renaming a key to fix its wording orphans existing records. Fix the visible label instead and leave the key alone.
• Em dashes inside quoted source titles, citation strings, and quote attribution ("...he said" lines). Those are typography, not rhythm crutches.
• The writer's voice traits identified in Step 1, and anything covered by an exception in references/voice.md.

Process

1. Inventory every copy surface in scope (markdown content, UI strings, seed data, metadata/titles, alt text). Ask the user for scope if unclear.

2. Read each file fully before editing. Apply humanizer + all six families above, including F (concept-unpacking), not just the word-level ones. Preserve structure and coverage: rewrite, don't delete.

3. Mechanical sweep afterward, in the edited files. This catches A-E; family F (concept-unpacking) is structural and won't show up in grep, so re-read the edited files once specifically for it after the sweep passes clean:

   • grep -rn "—\|–" (allow only inside direct quotes, source titles, and quote attribution)
   • grep -rniE "not just|not merely|isn't just|not only.*but"
   • grep -rniE ", one [a-z]+\.?$" (catches "X, one Y" headline candidates; not every hit is a violation, but check each)
   • grep -rniE "shipped|anti-pattern|proven out|leverage|workhorse|de facto|north star"
   • grep -rn "the enslaved\|the homeless"
   • grep -rniE "delve|foster|utilize|facilitate|empower|streamline|robust|cutting-edge|paradigm shift|game changer|tapestry|realm|beacon|multifaceted|meticulous|intricate|paramount|transformative|elevate|embark|supercharge|harness|ever-evolving"
   • grep -rniE "experts agree|studies show|many argue|widely regarded|observers (read|say)|analysts (say|consider)"
   • grep -rniE "it's worth noting|important to note|at the end of the day|at its core|in today's world|the reality is|in terms of|going forward|let's dive in"
   • grep -rniE "stands as a testament|pivotal moment|plays a vital role|solidifies its position|underscores its significance"
   • grep -rniE "\b(highlighting|underscoring|reflecting|showcasing|signaling|demonstrating)\b"
   • grep -rniE "here's the thing|let me be clear|i'll be honest|the uncomfortable truth|most people (skip|miss|get wrong)|nobody tells you"
   • grep -rniE "what if i told you|think about it:|plot twist:"
   • grep -rniE "^(in conclusion|ultimately,|overall,)"
   • grep -rniE "^[^:\n]{6,70}: [a-z]" (colon-reveal candidates; label colons are fine, check each)
   • grep -rnE "\b(just|literally|honestly|simply|actually|truly|fundamentally|importantly|crucially|inherently|inevitably)\b" (review every hit against the carve-out; do NOT bulk-delete)
   • grep -rnE "^\*\*[^*]{3,60}[.:]\*\*" (bold lead-in candidates; option labels a reader picks between are fine, paragraph hype is not)

   The same sweep ships as a runnable script: sweep.sh in this skill's directory. ./sweep.sh <files-or-dirs> prints every hit grouped by pattern, for humans or CI.

4. If the copy lives in a build artifact or database (embedded content, seeded tables), regenerate/redeploy and verify the LIVE text changed, not just the source.

5. Self-check the edited draft against references/eval.md yourself, answering each item pass or fail. Do not delegate this to a separate reviewer agent. If anything fails, fix it and run the checks again.

6. Show the user a summary of what changed with 3-5 before/after examples. For large jobs, offer a findings-first mode: list proposed changes and get approval before applying (that is how this process was originally run).

Output

Deliver: the edited files, the mechanical-sweep results proving the target patterns are gone, and the before/after summary. If anything was left intentionally (a quoted dash, a term of art, a motif instance), say so and why.