Writing Quality

Writing Quality — AI-ism Audit & Rewrite

You are editing content to remove AI writing patterns ("AI-isms") that make text sound machine-generated. This matters because client-facing deliverables can't afford AI-scented prose. AI-isms undermine the expert authority a paid deliverable is supposed to convey.

Modes

rewrite (default) — Flag AI-isms and rewrite the text to fix them. Use this during deliverable curation (Phase 1) and email drafting.

detect — Flag AI-isms only, no rewriting. Use when auditing existing content, when patterns might be intentional, or for a quick check before sending. Trigger detect mode when the user says "detect," "flag only," "audit only," "just flag," "scan," or similar. Default to rewrite mode otherwise.

In rewrite mode:

1. Audit and identify every AI-ism, citing specific text
2. Rewrite to remove all AI-isms
3. If the content cites external sources, run the citation check below before returning it
4. Return the cleaned text with a brief summary of major changes
5. If the user corrects the result, log it: bash scripts/log-correction.sh "<pattern-slug>" "<project>" — a REPEAT alert (exit 2) means propose the source-level fix (voice guide, template, this skill's rules), not another draft fix

In detect mode:

1. Audit and identify every AI-ism, citing specific text
2. Group by severity (P0, P1, P2)
3. Note which flags are clear problems vs. judgment calls
4. If the content cites external sources, run the citation check below

Context Profiles

Auto-detect from content cues. The user can override.

deliverable (default for anything going to a client) — Strictest. All rules at full strength. Consulting deliverables can't afford any AI smell. Clients pay for expert analysis, not generated filler.

email — Client correspondence. Strict on P0 and P1, relaxed on P2 structural issues (short emails don't need paragraph variation). Hedging rules relaxed slightly — "perhaps" is sometimes appropriate in diplomatic emails.

technical-blog — Long-form with code, architecture, APIs. Technical terms get a pass: robust, comprehensive, seamless, ecosystem, leverage (when describing actual platform APIs), facilitate, underpin, streamline are allowed. Still flag: delve, tapestry, beacon, embark, testament to, game-changer, harness. blog — Standard long-form prose (proposals, SOWs, reports not tied to a specific client deliverable). All rules apply at full strength.

Auto-detection cues

What to Remove or Fix

Formatting

Em dashes (— and --): Replace with commas, periods, parentheses, or rewrite as separate sentences. Target: zero per piece. Hard max: one per 1,000 words. Catch both Unicode em dashes (—) and double-hyphen substitutes (--).

Bold overuse: Strip bold from most phrases. One bolded phrase per major section max, or none. If something's important enough to bold, restructure the sentence to lead with it instead.

Excessive bullet lists: Convert bullet-heavy sections into prose paragraphs. Bullets only for genuinely list-like content (feature comparisons, step-by-step instructions, data parameters).

Sentence Structure

"It's not X — it's Y" constructions: Rewrite as a direct positive statement. Max one per piece, only if it genuinely serves the argument.

Hollow intensifiers: Cut "genuine," "truly," "quite frankly," "to be honest," "let's be clear," "it's worth noting that." Just state the fact.

Vague endorsement ("worth [verb]ing"): Cut "worth reading," "worth exploring," etc. Say why something matters instead.

Hedging: Cut "perhaps," "could potentially," "it's important to note that." Make the point directly. (Exception: email profile allows diplomatic hedging.)

Missing bridge sentences: Each paragraph should connect to the previous one. If paragraphs could be rearranged without the reader noticing, add connective tissue.

Compulsive rule of three: Vary groupings. Use two items, four items, or a full sentence instead of triads. Max one "adjective, adjective, and adjective" pattern per piece.

Words and Phrases to Replace

Three tiers based on how reliably they signal AI-generated text.

• Tier 1 — Always flag. These appear 5-20x more often in AI text than human text.
• Tier 2 — Flag in clusters. Fine alone, but 2+ in the same paragraph is a strong signal.
• Tier 3 — Flag by density. Common words AI overuses. Only flag at ~3%+ of total words.

Tier 1 — Always replace

Tier 2 — Flag when 2+ appear in the same paragraph

Tier 3 — Flag only at high density

Template Phrases (avoid)

Slot-fill constructions that signal generated text. If a phrase has a blank where any noun could go and still sound the same, it's too generic:

• "a [adjective] step towards [adjective] infrastructure" → describe the specific outcome
• "Whether you're [X] or [Y]" → pick the actual audience or cut
• "I recently had the pleasure of [verb]-ing" → just say what happened

Transition Phrases to Remove or Rewrite

• "Moreover" / "Furthermore" / "Additionally" → restructure, or use "and," "also"
• "In today's [X]" / "In an era where" → cut or state specific context
• "It's worth noting that" / "Notably" → just state the fact
• "Here's what's interesting" / "Here's what caught my eye" → let content signal importance
• "In conclusion" / "In summary" → your conclusion should be obvious
• "When it comes to" → just talk about the thing
• "At the end of the day" → cut
• "That said" / "That being said" → cut or use "but" / "however" sparingly

Structural Issues

Uniform paragraph length: Vary deliberately. Include 1-2 sentence paragraphs and longer ones. If every paragraph is roughly the same size, fix it.

Formulaic openings: If the piece opens with broad context before the point ("In the rapidly evolving world of..."), lead with the insight. Context can come second.

Suspiciously clean grammar: Don't sand away all personality. Deliberate fragments, sentences starting with "And" or "But," comma splices for effect — keep them if the natural voice uses them.

Pattern Categories (condensed — flag all of these)

Significance inflation: "marking a pivotal moment in the evolution of..." — state what happened, let the reader judge. If the sentence works after deleting the inflation, delete it.

Copula avoidance: AI avoids "is" and "has" by substituting "serves as," "features," "boasts," "presents," "represents." Default to "is" or "has" unless a specific verb adds meaning.

Synonym cycling: AI rotates synonyms to avoid repetition: "developers... engineers... practitioners... builders" in the same paragraph. Human writers repeat the clearest word.

Vague attributions: "Experts believe," "Studies show" — without naming the source. Either cite specifically or drop the attribution.

Filler phrases: "It is important to note that," "In terms of," "The reality is that" — cut.

Generic conclusions: "The future looks bright," "One thing is certain" — cut or make specific.

Chatbot artifacts: "I hope this helps!", "Certainly!", "Great question!", "Feel free to reach out" — remove entirely. Also: "In this article, we will explore..." and "Let's dive in!"

"Let's" constructions: "Let's explore," "Let's break this down" — false-collaborative openers that delay the point. Just start with the point.

Superficial -ing analyses: Strings of present participles as pseudo-analysis: "symbolizing the commitment, reflecting decades of investment, and showcasing a new era" — cut or replace with specific facts.

Promotional language: Tourism-brochure prose: "a vibrant hub of innovation," "a thriving ecosystem." Replace with plain description.

False ranges: "from ancient civilizations to modern startups" — sounds sweeping, says nothing. List the actual topics or pick the one that matters. Cutoff disclaimers: "As of my last update," "While specific details are limited" — model limitations leaking into prose. Find the information or remove the hedge entirely.

Novelty inflation: Treating established concepts as discoveries: "He introduced a term," "a concept nobody's naming." Describe what the person did with the concept, not that they discovered it.

Emotional flatline: Claiming emotions without conveying them: "What surprised me most," "I was fascinated to discover." If the thing is surprising, the reader should feel that from the content, not from the writer announcing it.

False concession structure: "While X is impressive, Y remains a challenge" — sounds balanced without weighing anything. Make the concession specific or pick a side.

Rhetorical question openers: "But what does this mean for developers?" — if you know the answer, just say it.

Sycophantic tone / Acknowledgment loops: "Great question!", "You're asking about..." — remove entirely.

Reasoning chain artifacts: "Let me think step by step," "Breaking this down" — internal scaffolding that doesn't belong in published prose.

Rhythm and Uniformity

Structure is the #1 AI detection signal. Consistent sentence construction, uniform pacing, and symmetrical phrasing are harder to mask than swapping flagged words.

• Sentence length: Mix short punchy sentences (3-8 words) with longer ones (20+). Fragments work. Questions break monotony.
• Paragraph length: Some should be one sentence. Some longer. No metronomic uniformity.
• Read-aloud test: If it sounds like text-to-speech, it's too uniform.
• Missing first-person: Where appropriate, the writer should have opinions and preferences. AI is relentlessly neutral.
• Over-polishing: Don't sand away all personality. Natural disfluency and idiosyncratic word choices keep text human.

When to Rewrite from Scratch vs. Patch

If the text has 5+ flagged vocabulary hits across multiple categories, 3+ distinct pattern categories triggered, and uniform sentence/paragraph length — patching won't fix it. The structure itself is AI-generated. State the core point in one sentence, then rebuild.

Empty Prose — the sentence that reads fine and says nothing

⚠ This is a different defect from an AI-ism, and every rule above will miss it. AI-isms are stylistic tics — "delve", "it's not just X, it's Y", dash overuse. Empty prose is grammatical, sounds like a person wrote it, and carries no content:

"We check the spec against reality."

Nothing there is machine-flavoured. It is still slop, because a reader cannot say what would be different if it were true. (Caught 2026-09-02: one draft carried 13 of these. That was the worst.)

THE ONE QUESTION

Read the sentence with no surrounding context, then ask:

Could a reader say what would be different if this were true?

If not, it is empty, and the fix is always the same shape: replace the abstraction with the operation it stands for. Check the spec against reality becomes "a script opens the file, prints the real number, and you compare it to the number typed in the spec."

This question catches emptiness no word list ever will. Slop regenerates — ban "leverage" and you get "harness".

Five families, and the move for each

Lead with a scene, not a definition

Added 2026-09-02 after a draft came back twice. An explanation that opens by defining its subject ("a spec is full of statements of fact") makes the reader assemble the situation themselves. One that opens with a specific scenario already in motion does not:

We're doing X. Then Y happens. Here is what breaks, and here is how we handle it.

Test it by reading your opening and asking the reader's questions back at it: what specifically? whose? why would that matter to me? If the paragraph does not already answer them, it is a definition wearing a narrative coat.

The mechanical half

The script catches recurring offenders — five classes, under a second, same answer every run. Its limits are deliberate and stated in its own source:

• It catches yesterday's offenders only. A phrase list cannot see novel emptiness; that is what THE ONE QUESTION is for, and the test suite asserts that limit on purpose (case K1).
• Code spans, fenced blocks, a file's --- header block and HTML attributes are exempt. An insider term is only a defect in prose somebody reads.
• False positives are the failure mode. Patterns are narrow by design. A gate that cries wolf gets clicked through, and then it is not a gate.

python3 .claude/hooks/check-empty-prose.py <file>   # exit 1 on any finding
bash    .claude/hooks/test-empty-prose.sh           # 11 cases, both directions
python3 .claude/hooks/mutate-empty-prose.py         # 9 mutations; proves the suite can fail

Grow the lists from prose actually caught in review — never from words that merely sound bad. When a correction lands, log it; a REPEAT alert is the signal to add the phrase to the list, rather than to fix that one draft again.

Unverified Assertion — the claim that rests on nothing

A claim that reads as established fact but rests on adjacent context instead of a source anyone checked. It is the most frequent correction on client-facing drafts, and prohibiting it at the behavioural level does not stop it — it recurs at the point where prose is written, so the check belongs here too.

Before releasing any client-facing draft, sweep every factual claim and sort it:

Two tells worth their own line. Proper nouns taken from transcripts are mis-transcribed constantly — near-homophone first names especially — so check a name against a contact record before one reaches a client. And a hedge deleted while editing is a new assertion: cutting "probably" is making a claim.

Internal Filing-System Artifacts — the audience boundary

Two questions, in order: who is this for? Then: what does the system need to remember? Serve the second without contaminating the first. System memory belongs on system surfaces — commit messages, changelogs, knowledge-base entries, memory files — never interleaved into a surface a client reads. Post-mortem notes in a commit message: right surface. The same notes in a client deliverable: wrong surface, same information.

Strip from any client-facing output:

• File-inventory tables ("what's in this folder") and package manifests
• Changelog references, version-history sections, deprecation and retrospective notes
• Internal record and database IDs, knowledge-base citations, registry or backlink references
• Repo paths (memory/, docs/, working/, drafts/, deliverables/)
• Governance or skill names, router language, "promoted YYYY-MM-DD" annotations

Conversion is authorship. Converting an in-repo file to a client format — markdown to .docx, a paste into email, a shared link — creates a NEW client deliverable and earns a full audit against this list. The repo source keeps its conventions; the client copy loses them. Derive the client copy first, then convert. Converting first and editing after is how the artifacts survive.

Scope and Volume Mismatch — the answer that does not fit the ask

It cuts both ways, which is why "be concise" does not fix it:

• Over-scoped — a narrow question gets a treatise, and the reader hunts for the answer.
• Under-scoped — a period report covers one meeting and silently drops the rest of the window.
• Wrong shape — an internal status dump shipped as a client update: jargon, task IDs, workstream codes.

The check: name the ask in one sentence, then confirm the draft answers exactly that — no less coverage, no extra freight. A status update covering a date range covers the whole range. A yes/no question gets the yes/no first, then the reason. If the draft reads as a laundry list, the reader was handed raw material instead of an answer.

Severity Tiers

P0 — Credibility killers (fix immediately)

• Cutoff disclaimers ("As of my last update")
• Chatbot artifacts ("I hope this helps!", "Great question!")
• Vague attributions without sources ("Experts believe")
• Significance inflation on routine events
• Reasoning chain artifacts leaking into prose
• Unverified assertions — a claim stated as fact that rests on inference, a conditional, or an unchecked source
• Internal filing-system artifacts in client-facing output

P1 — Obvious AI smell (fix before publishing)

• Scope or volume mismatch — the answer does not fit the ask, in either direction
• Word-list violations (delve, leverage, harness, robust, etc.)
• Template phrases and slot-fill constructions
• "Let's" transition openers
• Synonym cycling within a paragraph
• Formulaic openings ("In the rapidly evolving world of...")
• Bold overuse and em dash frequency (above 1 per 1,000 words)
• Sycophantic tone and acknowledgment loops

P2 — Stylistic polish (fix when time allows)

• Generic conclusions ("The future looks bright")
• Compulsive rule of three
• Uniform paragraph length
• Copula avoidance (serves as, features, boasts)
• Transition phrases (Moreover, Furthermore, Additionally)

Use P0+P1 for quick passes. Full audit covers all three tiers. Deliverable profile always does a full audit.

Self-Reference Escape Hatch

When writing about AI writing patterns (documentation, skill files, this file), quoted examples are exempt from flagging. Text inside quotation marks, code blocks, or explicitly marked as illustrative should not be rewritten.

Output Format

Rewrite mode (default)

Return your response in two sections:

1. Cleaned text The full rewritten content. Preserve the original structure, intent, and all specific technical details. Only change what the guidelines require.

2. What changed A brief summary of the major edits. Not every word — just the meaningful changes grouped by category (e.g., "Replaced 4 Tier 1 words, restructured 2 paragraphs for varied length, cut 3 filler transitions"). This lets the author learn what to avoid next time.

Detect mode

1. Issues found Bulleted list of every AI-ism identified, with offending text quoted. Grouped by severity.

2. Assessment For each flag, note whether it's a clear problem or a judgment call. If the text is clean, say so.

Tone Calibration

The goal is writing that sounds like a competent human wrote it. Direct. Specific. Five principles for human-sounding rewrites:

1. Vary sentence length — mix short with long. Fragments are fine.
2. Be concrete — replace vague claims with numbers, names, dates, or examples.
3. Have a voice — where appropriate, use first person, state preferences, show reactions.
4. Cut the neutrality — humans have opinions. If the piece should take a position, take it.
5. Earn your emphasis — don't tell the reader something is interesting. Make it interesting.

If the original writing is already strong, say so and make only necessary cuts. Don't over-edit for the sake of it. The replacement table provides defaults, not mandates — if a flagged word is clearly the right choice in context, preserve it.

Citations — the one pattern this skill cannot see

Every rule above is about how the prose sounds. A fabricated or misattributed citation sounds perfect — that is the whole problem, and no amount of reading the text catches it.

When the content cites an external source — a URL, a paper, a statistic, a claim attributed to a named third party — run evidence-auditor before the rewritten version ships. Client-facing work with a citation that does not trace is worse than client-facing work that reads like a machine.

Agent(
  subagent_type="evidence-auditor",
  description="Verify citations trace before the rewrite ships",
  prompt="Content: <paste the text with its citations>. Sources available: <paste paths or URLs>. For EACH citation, quote, statistic and claim attributed to a named third party, report TRACES / MISATTRIBUTED / UNVERIFIABLE, naming the source location that decides it. Judge only whether the claim traces to its source — the prose style is out of scope. Do not rewrite anything."
)

Anything back as MISATTRIBUTED or UNVERIFIABLE is fixed or cut before the content ships. Do not soften it into a hedge — a hedged fabrication is still a fabrication.

Integration Points

Run this skill automatically in these cases:

1. Deliverable curation — Before formatting any client-facing document, run in rewrite mode with the deliverable profile.
2. Client email drafting — When drafting emails longer than 3 sentences to external contacts, run in rewrite mode with the email profile. Quick internal replies are exempt.
3. On-demand audit — When the user says "check this for AI patterns" or similar, run in whichever mode the user requests.

Adapted from conorbronsdon/avoid-ai-writing v3.3.0 (MIT license).