prose-slop-guard
The problem this solves
AI-slop prose passes every existing gate. Tests don't read English. Render
review checks pixels. Code review checks logic. A doc full of em dashes,
"delve", and "it's not X, it's Y" ships green — and readers clock it as
machine-written in two sentences, which costs the text its credibility no
matter how correct it is.
Worse, the author-model can't self-grade: the same distribution that produced
the tells rates them as fine. Community consensus (HN, on anti-slop skills)
is blunt about this — filtered output can still read as slop when the filter
and the writer are the same pass.
So the fix is the same shape as design-token-guard and
class-extraction-guard: a source-level gate with a deterministic layer a
hook can run, plus a fresh-eyes judgment pass for the tells no regex can
catch. The canonical spec is Wikipedia's
Signs of AI writing
page — the same ground truth the Humanizer skill family builds on — mirrored
and condensed in references/slop-patterns.md.
Layer 1 — Lexical audit (deterministic)
Run the bundled checker from the project root:
python3 SKILL_DIR/scripts/check_prose_slop.py --root .
What it catches (the mechanical tells):
| rule |
catches |
default |
no-em-dash |
em/en dashes in prose (use -, comma, or parentheses) |
error |
banned-phrases |
throat-clearing openers, "not only... but also", "it is worth noting", "a testament to", "let's dive in", "ever-evolving" |
error |
sycophancy |
"great question", "you're absolutely right", "I hope this helps" |
error |
banned-vocabulary |
delve, leverage, seamless, tapestry, unleash, harness, elevate, landscape, game-changer, paradigm, synergy, empower, streamline, unprecedented, testament, boasts, furthermore... (each with a plain replacement hint) |
warn |
negative-parallelism |
"it's not just...", "isn't merely..." setups |
warn |
Scoping is prose-aware: fenced code blocks, inline code, link targets, URLs,
YAML frontmatter, and blockquotes are skipped (quoted content keeps its
author's punctuation — an em dash inside a quote is not your finding).
Useful flags:
--staged — only git-staged files (what the pre-commit hook runs).
--stdin — pipe a commit message or PR body through the same rules:
git log -1 --format=%B | python3 .../check_prose_slop.py --stdin
--json — { ok, summary, findings } for a gate/CI to parse.
PATHS… — limit to the files you just wrote.
Exit code 1 on error-severity findings, 0 when clean — drops straight into
a hook or CI step.
Layer 2 — Judgment pass (model, fresh eyes)
The regex layer cannot see rhythm, structure, or voice. After (or instead of,
for a quick review) the lexical audit, read references/slop-patterns.md and
sweep the text for the judgment-level categories:
- Rule-of-three rhythm — triplet lists as a crutch ("fast, simple, and
powerful"). One is fine; a pattern is a tell.
- Bullet soup / formatting inflation — bullets, bold, and headers where a
paragraph would carry the argument. Structure should encode information, not
decorate it.
- Vague attribution — "experts say", "studies show", "many users report"
with no named source. Name it or cut it.
- Inflated symbolism — "stands as", "serves as a reminder", "underscores
the importance of". State the fact; skip the ceremony.
- Superficial -ing analysis — trailing participial glosses ("...,
highlighting the need for...", "..., showcasing its versatility").
- Hedged everything-ness — "whether you're a beginner or an expert".
- Sycophantic or performative openers/closers in context the regexes miss.
Rewrite toward the require-list: short active sentences with varied length,
direct "you/your" address, concrete examples over abstractions, specific
attribution, direct claims with evidence, prose paragraphs by default.
Who runs the judgment pass matters. If you wrote the text this session, do
not grade it yourself — dispatch a fresh-context reviewer (a subagent that gets
only the text plus references/slop-patterns.md, not your drafting context) or
run the lexical checker plus a self-sweep and say plainly that the judgment
pass was self-graded. This is the same evaluator principle as
loop-controller's fresh-context evaluator: the writer's context contaminates
the grade.
Interpret and fix
Two kinds of findings, different fixes — don't blur them:
- Mechanical (em dash, banned word, banned phrase): replace per the hint.
Safe, fast, no meaning change.
- Judgment (rule of three, vague attribution, bullet soup): these usually
signal a missing fact, not a wrong word. "Studies show" means go find the
study or delete the claim. A triplet means pick the one that matters.
Rewriting the surface while keeping the emptiness is how "humanized" text
still reads as slop.
Legitimate exceptions — leave these alone and, where recurring, encode them
in config: quoted material (already exempt), upstream changelog text,
vocabulary that is a real term of art in the domain ("harness" in an agent
harness, "landscape" in ecology), and any project whose house style explicitly
allows em dashes ("rules": {"no-em-dash": "warn"}). The guard serves the
project's voice; it does not impose one.
Enforce (scaffold into the repo)
A one-time cleanup doesn't stop regression — the next generated README
reintroduces everything. Wire the gate in:
- Write
.prose-guard.json at the repo root (template:
assets/prose-guard.config.json). Tune rules, add domain terms to
allowVocabulary, scope extensions/skipPaths.
- Add a script entry —
"lint:prose": "python3 scripts/check_prose_slop.py --root ."
(copy the checker into the project's scripts/ or reference the skill path).
- Pre-commit hook — run
check_prose_slop.py --staged; block on errors.
Wire via Husky/lefthook if present, else a plain .git/hooks/pre-commit.
- CI step — run
lint:prose next to lint/typecheck.
- Standing style rules — for repos where agents generate prose routinely,
add the CLAUDE.md block from
references/wiring-into-agents.md so the rules
apply at generation time, not just at gate time. Prevention beats filtering.
Tell the user which layers you installed and which you skipped.
Using it as an agent / orchestrator gate
- A docs-agent (or any agent producing READMEs, docs, PR bodies) runs the
checker with
--json against the files it changed before reporting done;
error findings mean the task isn't done.
- The orchestrator runs it at the wave gate alongside typecheck/test;
non-zero
summary.errors blocks the wave and routes back to the owning
agent.
- git-pr pipes the drafted PR body through
--stdin before gh pr create.
- The judgment pass at gate time goes to a fresh-context reviewer, never
the agent that wrote the text.
Exact snippets: references/wiring-into-agents.md.
Reference files
references/slop-patterns.md — the full pattern catalog by category
(Vocabulary, Phrases, Structure, Voice, Sycophancy, Rhythm, Specificity,
Formatting), each with why it reads as slop and what to write instead;
provenance and upstream sources.
references/wiring-into-agents.md — agent self-check, orchestrator
wave-gate, git-pr --stdin check, the fresh-context evaluator dispatch, and
the copy-paste CLAUDE.md standing-rules block.
1---2name: prose-slop-guard3version: 1.0.04composes_with: ["orchestrator", "docs-agent", "code-review-agent", "git-pr", "wiki-research", "interactive-doc", "llm-wiki", "skill-writer"]5description: >-6 Source-level gate that catches AI-slop prose ("claudenese") before it ships:7 em dashes, AI vocabulary (delve, leverage, seamless, tapestry), negative8 parallelism ("it's not X, it's Y"), throat-clearing openers, sycophantic9 filler, rule-of-three rhythm, bullet soup. Use whenever writing or reviewing10 outward prose — READMEs, docs, announcements, blog posts, PR descriptions,11 wiki pages, marketing copy — before committing or declaring a writing task12 done, when setting up enforcement so slop can't ship again, or as an13 orchestrator/docs-agent wave-gate. Trigger on: "sounds like AI",14 "reads as AI-written", "humanize this", "make it sound human", "de-AI this",15 "too ChatGPT", "AI tells", "AI slop", "claudenese", "stop writing like a16 bot". A deterministic lexical checker plus a judgment rewrite pass; don't17 skip it because it "looks fine" — self-grading is the failure mode this18 guards.19compatibility: Claude Code or any host with Bash; requires Python 3.8+ (stdlib only) for scripts/check_prose_slop.py20allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]21metadata:22 source: https://skillmd.com/skills/ivy00johns/prose-slop-guard23---2425# prose-slop-guard2627## The problem this solves2829AI-slop prose passes every existing gate. Tests don't read English. Render30review checks pixels. Code review checks logic. A doc full of em dashes,31"delve", and "it's not X, it's Y" ships green — and readers clock it as32machine-written in two sentences, which costs the text its credibility no33matter how correct it is.3435Worse, the author-model can't self-grade: the same distribution that produced36the tells rates them as fine. Community consensus (HN, on anti-slop skills)37is blunt about this — filtered output can still read as slop when the filter38and the writer are the same pass.3940So the fix is the same shape as `design-token-guard` and41`class-extraction-guard`: a **source-level gate** with a deterministic layer a42hook can run, plus a **fresh-eyes judgment pass** for the tells no regex can43catch. The canonical spec is Wikipedia's44[Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)45page — the same ground truth the Humanizer skill family builds on — mirrored46and condensed in `references/slop-patterns.md`.4748## Layer 1 — Lexical audit (deterministic)4950Run the bundled checker from the project root:5152```bash53python3 SKILL_DIR/scripts/check_prose_slop.py --root .54```5556What it catches (the mechanical tells):5758| rule | catches | default |59|---|---|---|60| `no-em-dash` | em/en dashes in prose (use ` - `, comma, or parentheses) | error |61| `banned-phrases` | throat-clearing openers, "not only... but also", "it is worth noting", "a testament to", "let's dive in", "ever-evolving" | error |62| `sycophancy` | "great question", "you're absolutely right", "I hope this helps" | error |63| `banned-vocabulary` | delve, leverage, seamless, tapestry, unleash, harness, elevate, landscape, game-changer, paradigm, synergy, empower, streamline, unprecedented, testament, boasts, furthermore... (each with a plain replacement hint) | warn |64| `negative-parallelism` | "it's not just...", "isn't merely..." setups | warn |6566Scoping is prose-aware: fenced code blocks, inline code, link targets, URLs,67YAML frontmatter, and blockquotes are skipped (quoted content keeps its68author's punctuation — an em dash inside a quote is not your finding).6970Useful flags:71- `--staged` — only git-staged files (what the pre-commit hook runs).72- `--stdin` — pipe a commit message or PR body through the same rules:73 `git log -1 --format=%B | python3 .../check_prose_slop.py --stdin`74- `--json` — `{ ok, summary, findings }` for a gate/CI to parse.75- `PATHS…` — limit to the files you just wrote.7677Exit code `1` on error-severity findings, `0` when clean — drops straight into78a hook or CI step.7980## Layer 2 — Judgment pass (model, fresh eyes)8182The regex layer cannot see rhythm, structure, or voice. After (or instead of,83for a quick review) the lexical audit, read `references/slop-patterns.md` and84sweep the text for the judgment-level categories:8586- **Rule-of-three rhythm** — triplet lists as a crutch ("fast, simple, and87 powerful"). One is fine; a pattern is a tell.88- **Bullet soup / formatting inflation** — bullets, bold, and headers where a89 paragraph would carry the argument. Structure should encode information, not90 decorate it.91- **Vague attribution** — "experts say", "studies show", "many users report"92 with no named source. Name it or cut it.93- **Inflated symbolism** — "stands as", "serves as a reminder", "underscores94 the importance of". State the fact; skip the ceremony.95- **Superficial -ing analysis** — trailing participial glosses ("...,96 highlighting the need for...", "..., showcasing its versatility").97- **Hedged everything-ness** — "whether you're a beginner or an expert".98- **Sycophantic or performative openers/closers** in context the regexes miss.99100Rewrite toward the require-list: short active sentences with varied length,101direct "you/your" address, concrete examples over abstractions, specific102attribution, direct claims with evidence, prose paragraphs by default.103104**Who runs the judgment pass matters.** If you wrote the text this session, do105not grade it yourself — dispatch a fresh-context reviewer (a subagent that gets106only the text plus `references/slop-patterns.md`, not your drafting context) or107run the lexical checker plus a self-sweep and say plainly that the judgment108pass was self-graded. This is the same evaluator principle as109`loop-controller`'s fresh-context evaluator: the writer's context contaminates110the grade.111112## Interpret and fix113114Two kinds of findings, different fixes — don't blur them:115116- **Mechanical** (em dash, banned word, banned phrase): replace per the hint.117 Safe, fast, no meaning change.118- **Judgment** (rule of three, vague attribution, bullet soup): these usually119 signal a missing fact, not a wrong word. "Studies show" means *go find the120 study or delete the claim*. A triplet means *pick the one that matters*.121 Rewriting the surface while keeping the emptiness is how "humanized" text122 still reads as slop.123124**Legitimate exceptions** — leave these alone and, where recurring, encode them125in config: quoted material (already exempt), upstream changelog text,126vocabulary that is a real term of art in the domain ("harness" in an agent127harness, "landscape" in ecology), and any project whose house style explicitly128allows em dashes (`"rules": {"no-em-dash": "warn"}`). The guard serves the129project's voice; it does not impose one.130131## Enforce (scaffold into the repo)132133A one-time cleanup doesn't stop regression — the next generated README134reintroduces everything. Wire the gate in:1351361. **Write `.prose-guard.json`** at the repo root (template:137 `assets/prose-guard.config.json`). Tune rules, add domain terms to138 `allowVocabulary`, scope `extensions`/`skipPaths`.1392. **Add a script entry** — `"lint:prose": "python3 scripts/check_prose_slop.py --root ."`140 (copy the checker into the project's `scripts/` or reference the skill path).1413. **Pre-commit hook** — run `check_prose_slop.py --staged`; block on errors.142 Wire via Husky/lefthook if present, else a plain `.git/hooks/pre-commit`.1434. **CI step** — run `lint:prose` next to lint/typecheck.1445. **Standing style rules** — for repos where agents generate prose routinely,145 add the CLAUDE.md block from `references/wiring-into-agents.md` so the rules146 apply at generation time, not just at gate time. Prevention beats filtering.147148Tell the user which layers you installed and which you skipped.149150## Using it as an agent / orchestrator gate151152- A **docs-agent** (or any agent producing READMEs, docs, PR bodies) runs the153 checker with `--json` against the files it changed *before* reporting done;154 error findings mean the task isn't done.155- The **orchestrator** runs it at the wave gate alongside typecheck/test;156 non-zero `summary.errors` blocks the wave and routes back to the owning157 agent.158- **git-pr** pipes the drafted PR body through `--stdin` before `gh pr create`.159- The **judgment pass** at gate time goes to a fresh-context reviewer, never160 the agent that wrote the text.161162Exact snippets: `references/wiring-into-agents.md`.163164## Reference files165166- `references/slop-patterns.md` — the full pattern catalog by category167 (Vocabulary, Phrases, Structure, Voice, Sycophancy, Rhythm, Specificity,168 Formatting), each with why it reads as slop and what to write instead;169 provenance and upstream sources.170- `references/wiring-into-agents.md` — agent self-check, orchestrator171 wave-gate, git-pr `--stdin` check, the fresh-context evaluator dispatch, and172 the copy-paste CLAUDE.md standing-rules block.