Stop sounding like a machine, you dumb machine.
"Not X. Y." Rhythmically satisfying, costs no thought, and it turns up in clusters. A person reaches for it once, when the contrast is the point. A model reaches for it whenever a sentence needs shape.
A benefit bolted onto a sentence with no subject committed to it. Search for , ensuring , allowing , enabling , driving and rewrite each as its own sentence, or cut it.
Em dash, en dash, smart quotes, ellipsis. The most cited tell and the easiest to over-correct: swapping every em dash for a semicolon reads as evasive. Prefer a full stop. Watch the HTML entity forms too, since ’ slips past a check written for the raw character.
Every sentence between 15 and 25 words. Every paragraph three to four sentences. Human writing swings hard, and a four-word sentence after a thirty-word one is a choice a model rarely makes unprompted. Read a paragraph aloud: if your breath falls in the same place every time, the rhythm is flat.
leverage, robust, seamless, streamline, holistic, cutting-edge, tapestry, delve, foster, underscore, pivotal, testament, unlock, empower, elevate, transformative, synergy, paradigm, myriad, bespoke, curated, actionable. None are banned. Each has to survive one question: would a practitioner say this out loud to a colleague?
"It is worth noting that", "Importantly", "That said", "At the end of the day", "Ultimately". Nearly all of it deletes with no loss. If a point is important, its position in the paragraph should say so.
"Studies show", "experts agree", "research suggests". Name the source and the date, or cut the claim. This one is not only a voice problem.
Three items, every time. Three sections, three bullets, three adjectives. Three is a good number, which is why the habit hides. The tell is when everything is three, including the things that are naturally two or five.
Save it anywhere on your path. It takes one file or many, and --summary gives one line per file for scanning a whole set at once.
The rules behind every check. Section 04 covers what is in it.
Put both files, voice_check.py and Human_Voice_Standard.md, into a Claude project alongside your document, then ask Claude to run the checker. The report comes back in the chat. With the standard in there too, it can say why a hit matters and rewrite against the rules instead of guessing at them.
Six steps below. Worth it if you check a lot of files, or want to scan a whole folder at once.
Terminal on a Mac, in Applications, Utilities. PowerShell on Windows, from the Start menu. Everything below is typed at the prompt and run with Enter.
A version of 3 or higher and you are set. If the command is not found, try python --version and use python throughout. If neither works, install it from python.org.
python3 --version
Download voice_check.py into the same folder as the document you want to check.
cd is change directory. Type cd and a space, then drag the folder from Finder or File Explorer onto the terminal window to fill in the path.
cd /Users/you/Documents/drafts
Use your own file name and extension. The report prints into the terminal.
python3 voice_check.py my-draft.md
*.md means every markdown file. One line per file, so you know which ones to open. --only chases a single pattern.
python3 voice_check.py --summary *.md python3 voice_check.py --only antithesis,tails my-draft.md
In a terminal, you see this.
$ python3 voice_check.py product-update.md ============================================================================== voice_check: product-update.md 155 words of visible copy ============================================================================== [FIX ] Non-ASCII punctuation 2 hit(s) Em dash, en dash, smart quotes, ellipsis. House rule is pure ASCII. Do this: Replace with plain ASCII. A full stop usually beats a dash. L9 In order to reduce failures, we added retries — three of them. use a full stop, or a comma L19 It’s the SDK that slipped. use ' tokens: — x1, ’ x1 [OK ] Antithesis reflex 2 hit(s) budget 2 "Not X. Y." The strongest machine cadence. Budget two per document. Do this: Say the positive thing straight. Drop the "not X" half, or split it in two. L5 The scheduler is not just faster. It is a different system. L21 Reporting is not the point. tokens: is not just faster. it is x1, is not the point x1 [OK ] Participial benefit tails 1 hit(s) budget 2 ", ensuring/allowing/enabling..." Attaches a benefit without a subject. Do this: Give the benefit its own sentence, or cut it. L6 so jobs run in parallel, ensuring throughput scales with the worker pool rather than [OK ] Soft contrast connectives 2 hit(s) budget 3 "rather than", "instead of". Fine in ones, a tell in volume. Do this: Keep the sharpest one or two. Rewrite the rest as plain statements. L6 so jobs run in parallel, ensuring throughput scales with the worker pool rather than L16 Instead of asking teams to change how tokens: rather than x1, instead of x1 [OK ] Corporate abstraction vocabulary 2 hit(s) budget 2 Would a practitioner say this out loud to a colleague? Do this: Swap for the word you would use out loud with a colleague. L15 Our platform is robust and seamless. L15 Our platform is robust and seamless. tokens: robust x1, seamless x1 [CLEAN ] Signposting filler 0 hit(s) budget 0 [CLEAN ] Hedging stacks 0 hit(s) budget 0 [FIX ] Vague attribution 1 hit(s) Name the source and date, or cut the claim. Proof discipline, not just voice. Do this: Name the source and the date, or cut the claim. L10 Studies show that retry logic recovers most transient [REVIEW] Wordiness 2 hit(s) budget 0 Shorter form exists and means the same thing. Do this: Use the shorter form shown. L9 In order to reduce failures, we added retries — three of them. use to L9 The fact that a job failed once use that tokens: in order to x1, the fact that x1 [CLEAN ] Three-item lists 0 hit(s) budget 4 [REVIEW] Unexplained acronyms 2 found Pinker, the curse of knowledge. Spell it out on first use. L19 API The API is stable. L19 SDK It’s the SDK that slipped. [REVIEW] Rhythm 16 sentences mean 5.9 words, spread 2.0, variation 0.33, short sentences 94%, longest flat run 1 variation is low, sentences are too uniform Human writing swings. Break a long sentence, or cut one short. ------------------------------------------------------------------------------ 12 total hits across 5 pattern(s) needing a look. Each hit shows the whole sentence it sits in. Search for that sentence in your document, or open the file at the line number. Nothing is changed for you. TO GET REWRITES: paste this whole report into a chat that has Human_Voice_Standard.md loaded, and ask it to rewrite the flagged sentences. Keep the meaning, show before and after, leave the good ones. ------------------------------------------------------------------------------
FIXREVIEWokcleanEach check says what to do about it. Where there is only one right answer, like in order to becoming to, it prints the swap. Where judgment is needed it names the move instead, because a canned replacement would be wrong too often. It never edits your file.
In a Claude project holding both files, you see this. The check and the rewrites arrive together.
Pick the ones that land and say so in a sentence. All three, two of them, one of them, none of them. Then ask for the updated draft. You get a new copy back, and the file you uploaded stays as it was.
Every hit prints the whole sentence it sits in. Copy that sentence, paste it into Find in Word, Docs, or wherever you are drafting, and rewrite it there.
In a project holding both files, ask Claude to run the checker. The report and the suggested rewrites come back together, because the standard is right there. Read them: every rewrite is a judgment somebody made, and you decide which ones land.
Open the file at the line number. Works for markdown and plain text. On HTML the line holds markup as well, so the sentence is still the faster way in.
Three parts.
Detection covers sixteen patterns in full, including the ones no regex will ever find. Narrative is StoryBrand applied to real work: the reader is the hero, you are the guide, and a problem has three levels rather than one. Mechanics is concision, heading conventions, house rules, and a nine step check pass.
Those last two parts have nothing to do with machines. Brevity is power. Every word earns its place. If a thing can be said shorter and simpler, it has to be. Being understood by everyone in the room beats sounding like the smartest person in it.
The curse of knowledge. You cannot imagine not knowing what you already know, so you skip the step that seemed obvious and use the word your team uses. Pinker calls it the best single explanation of why good people write bad prose. It is our most common failure by a distance.
The customer is the hero and you are the guide. Three levels of problem, not one. The grunt test, the BrandScript, the one-liner. His rule: if you confuse, you lose. Most companies are beaten on being understood, not on product.
Sentences all the same length drone, and the ear stops listening. Vary the length and the writing finds a rhythm. His demonstration passage is why the checker measures sentence variance at all.
If a word can come out, take it out. Never reach for a long word where a short one does the job, or a figure of speech you are used to seeing in print. Most of the concision rules trace back here.
Omit needless words. Vigorous writing is compact, in the way a drawing has no unnecessary lines. The subtraction pass is theirs.
It finds patterns and flags what might be a problem. You are the human in the loop. It is ultimately up to you to polish your art, craft, and content.