Skip to content
Back to search

unslop

SkillWorks with Claude CodeGitHub

Edit or audit prose for AI writing patterns. Use when someone wants to humanize a draft, remove slop, flag robotic phrasing, or learn and write in an author's voice.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theclaymethod-unslop/badge.svg)](/listings/theclaymethod-unslop)

HTML

<a href="/listings/theclaymethod-unslop"><img src="/api/listings/theclaymethod-unslop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using the Skills CLI (recommended)

Install to any supported coding agent with [npx skills](https://github.com/vercel-labs/skills):

# Install to Claude Code (global)
npx skills add theclaymethod/unslop -g -a claude-code

# Install to several agents at once
npx skills add theclaymethod/unslop -g -a claude-code -a cursor -a codex

# Install to every detected agent
npx skills add theclaymethod/unslop -g

# List available skills first
npx skills add theclaymethod/unslop --list

Manual installation

git clone https://github.com/theclaymethod/unslop.git ~/dev/unslop
ln -s ~/dev/unslop ~/.claude/skills/unslop
# Or wire it as a slash command:
ln -s ~/dev/unslop/SKILL.md ~/.claude/commands/unslop.md

The Python scripts under `scripts/` run on their own, with no third-party dependencies, just Python 3.8+ and the standard library. Call them from CI, a pre-publish check, or another agent, and you never load the skill at all.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 38 lines
  1. ---
  2. name: unslop
  3. description: Edit or audit prose for AI writing patterns. Use when someone wants to humanize a draft, remove slop, flag robotic phrasing, or learn and write in an author's voice.
  4. license: MIT
  5. user-invocable: true
  6. argument-hint: "[teach · cleanup · rewrite · mimic] [input]"
  7. metadata:
  8. author: claytonkim
  9. version: "2.3.0"
  10. ---
  11. # Unslop
  12. Open the matching command before acting. Input can be pasted text, a file, or stdin.
  13. For audits and rewrites, [the core contract](references/core-contract.md) governs what to edit and preserve.
  14. ## Routing by phrase
  15. | Request | Command |
  16. |---------|---------|
  17. | `rewrite`, humanize a draft, or bare `/unslop <text>` | [references/commands/rewrite.md](references/commands/rewrite.md) |
  18. | `cleanup`, propose edits I can accept or reject | [references/commands/cleanup.md](references/commands/cleanup.md) |
  19. | audit, review before publication, flag only, or `--report` | [references/commands/cleanup.md](references/commands/cleanup.md#report-only) |
  20. | `teach`, build a voice profile | [references/commands/teach.md](references/commands/teach.md) |
  21. | harvest writing samples, what writing of mine do you have? | [references/commands/teach.md](references/commands/teach.md#1-gather-samples-harvest) |
  22. | calibrate my voice profile, quiz me on paired samples | [references/commands/teach.md](references/commands/teach.md#calibrate) |
  23. | `mimic` or draft in my voice | [references/commands/mimic.md](references/commands/mimic.md) |
  24. | refine until it sounds like me | [references/commands/mimic.md](references/commands/mimic.md#refine) |
  25. | voice check, does this sound like me? | [references/commands/mimic.md](references/commands/mimic.md#voice-check) |
  26. | add a newly observed AI tell to the library | [references/commands/contribute.md](references/commands/contribute.md) |
  27. ## Output Format
  28. Before writing, read the selected voice preset in `presets/`. The default is `crisp`; `--preset` also accepts `warm`, `expert`, and `story`.
  29. Return the cleaned text for a rewrite. For a report, give **Issues Found** (span, category, severity, contextual reason) and **Assessment** (confirmed defects and judgment calls). Preserve the original text in report mode.
  30. For strict or requested analysis, return **Transformed Text** and **Validation**. Report constraints preserved, before/after pattern counts, structure, readability grade, sentence variance, percentage changed, and rubric score. With `--strict`, scores below 32/40 fail. See [the rubric](references/rubric.md).
README.md · README · 512 lines
  1. # unslop
  2. unslop finds formulaic or unclear writing and makes targeted edits while preserving
  3. meaning and voice. It ships as an agent skill with standalone Python scanners.
  4. Four commands cover the whole surface:
  5. - `/unslop teach` builds a reusable voice from your own writing samples.
  6. - `/unslop cleanup` flags AI tells as reviewable suggestions and changes nothing on its own.
  7. - `/unslop rewrite` diagnoses a draft and rebuilds it under the guards (the default).
  8. - `/unslop mimic` drafts or rewrites in a taught voice, then clears every removal gate.
  9. Scanners suggest candidates; the agent checks each use in context. Rewrite gates
  10. check preservation and known defects. Neither a clean scan nor a familiar phrase
  11. proves who wrote the text, and the checks cannot guarantee that every defect is gone.
  12. ## What counts as proof
  13. UNSLOP's product claim is not the number of rules or passing repository checks. The core claim
  14. is narrower: on unfamiliar AI-generated or mixed prose, it should find genuine problems, repair
  15. them, and avoid damaging facts or already-good writing. The core benchmark therefore reports
  16. detection precision and recall, repair success, preservation, collateral-damage rate, and
  17. whole-document net improvement separately, plus byte-exact no-op behavior on clean prose. It
  18. also compares with the same Luna model
  19. working without the UNSLOP contract. See [`evals/CORE-BENCHMARK.md`](evals/CORE-BENCHMARK.md).
  20. The latest independent public result is a **no-ship**: UNSLOP materially improved recall and
  21. repair over plain Luna, but it did not yet meet the precision, damage, or whole-document safety
  22. bar. See [`evals/CORE-RESULTS.md`](evals/CORE-RESULTS.md) for the exact result and remaining
  23. failure modes.
  24. Results are divided into three scoreboards so supporting machinery cannot inflate the product
  25. result:
  26. - **Core product:** detection, repair, preservation, damage, and net improvement.
  27. - **Voice:** teach/mimic fidelity and its removal gates.
  28. - **Engineering:** scanner coverage, schemas, routing, caching, and repository regressions.
  29. The engineering suite can show that the implementation behaves as specified. Only the core
  30. scoreboard can show that the specification improves writing.
  31. The development runner supports OpenAI through Codex, Anthropic through Claude,
  32. Gemini, and open models through Cloudflare AI Gateway. Each model runs paired
  33. with-skill and without-skill arms under the same contract. See the
  34. [cross-family setup and evaluation protocol](evals/CORE-BENCHMARK.md#cross-family-development).
  35. Provider support is separate from demonstrated writing quality.
  36. ## Installation
  37. ### Using the Skills CLI (recommended)
  38. Install to any supported coding agent with [npx skills](https://github.com/vercel-labs/skills):
  39. ```bash
  40. # Install to Claude Code (global)
  41. npx skills add theclaymethod/unslop -g -a claude-code
  42. # Install to several agents at once
  43. npx skills add theclaymethod/unslop -g -a claude-code -a cursor -a codex
  44. # Install to every detected agent
  45. npx skills add theclaymethod/unslop -g
  46. # List available skills first
  47. npx skills add theclaymethod/unslop --list
  48. ```
  49. ### Manual installation
  50. ```bash
  51. git clone https://github.com/theclaymethod/unslop.git ~/dev/unslop
  52. ln -s ~/dev/unslop ~/.claude/skills/unslop
  53. # Or wire it as a slash command:
  54. ln -s ~/dev/unslop/SKILL.md ~/.claude/commands/unslop.md
  55. ```
  56. The Python scripts under `scripts/` run on their own, with no third-party dependencies, just
  57. Python 3.8+ and the standard library. Call them from CI, a pre-publish check, or another agent,
  58. and you never load the skill at all.
  59. ## Three Detection Layers
  60. Detection stacks three deterministic scanners, coarse to fine. Each one returns JSON and exits
  61. non-zero on a flag. False-positive examples protect tested literal and domain
  62. uses; unfamiliar contexts still need review.
  63. **Phrase layer** (`scripts/banned_phrase_scan.py`). The compact runtime pack has 16 literal
  64. triggers, each backed by contextual false-positive protection. Gated words fire only in their
  65. jargon collocations. Literal legal, medical, mechanical, historical, and technical uses stay
  66. clean. Quoted spans, blockquotes, and code fences are masked first, so a tutorial documenting
  67. bad writing does not flag its own examples.
  68. **Structure layer** (`scripts/structure_scan.py`). 36 structural patterns plus document-level
  69. metrics: `sentence_burstiness`, `paragraph_cv`, `triad_density`, `bold_colon_listicle_count`,
  70. `one_line_staccato_share`, `connective_paragraph_openers`, `signpost_density`,
  71. `opener_unique_ratio`, `top_opener_share`, `max_consecutive_opener`,
  72. `participial_closer_share`, `conclusion_coda`, and `summary_sandwich`. This layer catches the
  73. rhythm tells, the uniform sentence length and the staccato runs, the moralizing codas, the
  74. connective scaffolds that open every paragraph with `"However,"` or `"Moreover,"`, and the
  75. bold-label listicles that stand in for prose. Genre carve-outs keep it honest, so `--genre docs`
  76. allows the bold-label lists that reference docs really use, and `--genre social` allows the
  77. short-line cadence that belongs in social copy.
  78. **Silhouette layer** (`scripts/silhouette_scan.py`). This one sits a level above the surface and
  79. scores how the ideas are arranged. It catches outline-following, recap loops, and paragraph-role
  80. templating: body paragraphs that open on a discourse cue instead of their own claim
  81. (`scaffold_opener_share`), opening vocabulary that disappears mid-document and returns at the
  82. end (`callback_content`, the strongest single tell), cue-opener roles rotating like a template
  83. (`role_entropy_bits`), intro content words reappearing as body-paragraph heads
  84. (`preview_fulfillment`), and section headings that restate the intro's outline
  85. (`heading_preview`). The composite `silhouette_penalty` flags at `1.0` against a committed
  86. human reference. On the corpus in the repo it separates cleanly, with 12 of 12 AI documents
  87. flagged and 0 of 8 human documents flagged. A cue-deletion attack collapses the scaffold metric,
  88. so silhouette gets scored jointly with the structure scanner, as a lower fence.
  89. ## The Gamut: What Gets Removed
  90. Every family below is cataloged in `references/taboo-phrases.md` and pinned by an eval row.
  91. Severity is `hard` (always a tell) or `soft` (a default register guard your real voice can
  92. override). The idea throughout is contextual gating over blunt word bans, and a pattern ships
  93. only once a false-positive row proves the literal sense survives.
  94. ### Openers, emphasis, and inflation
  95. | Family | Caught examples |
  96. |--------|-----------------|
  97. | Throat-clearing openers | `"Here's the thing:"`, `"The uncomfortable truth is"`, `"Let me be clear"`, `"It turns out"`, `"Let's dive in"`, `"Let's unpack"` |
  98. | Emphasis crutches | `"Full stop."`, `"Let that sink in."`, `"Make no mistake"`, `"Read that again."`, `"This cannot be overstated."` |
  99. | The "X is real" closer | `"The struggle is real."`, `"The stakes are real."` (spares the literal "is it genuine?" sense) |
  100. | Significance inflation | `"stands as a testament to"`, `"pivotal moment"`, `"enduring legacy"`, `"rich tapestry"`, `"cornerstone of"`, `"holds great promise"` |
  101. | False agency | `"the numbers speak for themselves"`, `"the data tells a story"`, `"paints a clear picture"` |
  102. ### Contrast, questions, and drama
  103. | Family | Caught examples |
  104. |--------|-----------------|
  105. | Negative parallelism | `"It's not X, it's Y"`, `"Not only... but also"`, `"Not merely X, but Y"`, `"No X, no Y, just Z"` |
  106. | Contrastive definitions | `"X isn't a Y, it's a Z"` (spares real corrections like `"Use pnpm, not npm."` and `"The painting is real, not a forgery."`) |
  107. | Wh-opener self-Q&A | `"Why does this matter? Because..."`, `"What does this mean for..."`, `"Why should you care?"` |
  108. | Cliffhanger fragments | `"[Noun]. That's it. That's the [thing]."`, `"The ___ loop."` as a standalone, `"X things. One thing."` |
  109. | Hedge stacks | `"(and perhaps more importantly, ...)"`, `"(arguably ...)"`, `"While X is promising, Y remains a challenge"` |
  110. ### Attribution, flattery, and jargon
  111. | Family | Caught examples |
  112. |--------|-----------------|
  113. | Vague attribution | `"Experts argue"`, `"Studies show"`, `"Some critics"`, and bare clause-initial `"Research indicates"` (attributed and possessive forms stay clean) |
  114. | Reader-addressing flattery | `"Here's what's interesting"`, `"worth reading"`, `"worth your time"`, `"Whether you're a seasoned developer or just starting out"` |
  115. | Business-jargon collocations | `"navigate challenges"`, `"leverage synergies"`, `"deep dive"`, `"circle back"`, `"move the needle"`, `"low-hanging fruit"` |
  116. | Marketing and headline cadence | `"world-class"`, `"state-of-the-art"`, `"a hidden gem"`, two-beat imperative slogans (`"Emit 1,100 tokens. Ship 237KB."`), and headline slogan cadence firing at three or more short-line headers in one document |
  117. ### Chatbot residue and punctuation
  118. | Family | Caught examples |
  119. |--------|-----------------|
  120. | Chatbot artifacts | `"I hope this helps"`, `"Certainly!"`, `"Great question!"`, `"as an AI language model"`, `"as of my knowledge cutoff"` |
  121. | Emoji section headers | Decorative emoji standing in as headings, flagged as a formatting tell |
  122. | Em-dash overuse | The single most reliable punctuation tell. Default is zero; two or more in one paragraph is always a hard flag |
  123. | Reasoning-chain leaks | `"Let me think step by step"`, `"Breaking this down"`, `"Here's my thought process"` |
  124. ### Structural and silhouette families
  125. The structure scanner adds the document-shape tells: uniform sentence rhythm, staccato
  126. one-line-paragraph runs outside social copy, connective paragraph scaffolds, signpost density,
  127. and moralizing codas like `"Ultimately, this reminds us that..."`. The silhouette scanner adds
  128. the arrangement tells above. A handful of macro tells stay agent judgment instead of
  129. scanner-enforced (both-sidesism, templated redemption arcs, over-determination, uniform
  130. emotional register), because a scanner can't reliably tell a genuine opposing view from a
  131. manufactured one.
  132. ## What Gets Protected
  133. Do-no-harm is half the product. The scanners leave the following alone, and each guard has its
  134. own eval row.
  135. - **Register guards.** `"never store secrets"`, `"may cause drowsiness"`,
  136. `"does not establish causation"`, and `"notwithstanding anything to the contrary"` are
  137. content, not filler. In legal, medical, security, and scientific text, these hedges,
  138. negations, absolutes, and scope words carry meaning. `validate_preservation.py --strict`
  139. turns dropping one into a hard failure.
  140. - **Literal domain usage.** Construction, mechanics, law, medicine, finance, sailing, and
  141. code all use the gated words literally. Every contextual pattern ships with a false-positive
  142. row proving the literal sense stays clean.
  143. - **Quoted examples.** Spans in quotes, blockquotes, and code fences are exempt by default, so
  144. documentation never self-flags the bad writing it's teaching.
  145. - **Facts, with magnitude awareness.** Numbers, names, dates, quotes, units, references like
  146. `Section 12(b)`, and `and/or` scope survive a rewrite. Magnitude-aware checking means
  147. `$47.3M` can't silently become `$47.3 billion`, and `150 km` can't become `150 miles`.
  148. - **Genre carve-outs.** Bold-label lists are correct in reference docs, staccato is correct in
  149. social copy, and a section-roadmap abstract is academic convention rather than a tell.
  150. - **English only.** Non-English input gets cheap detection and a clear decline. That's the one
  151. graceful refusal in the product, and the scanners return `non_english: true` and stop.
  152. ## Voice: teach and mimic
  153. The right end of the axis writes the way a specific person writes. It's agent-driven end to
  154. end, and you supply approvals and answers, never a directory or a command.
  155. ### teach
  156. `teach` distills your samples into two artifacts under `.unslop/voice/<name>/` (gitignored):
  157. a machine profile (`profile.json`, the deterministic referee) and a layered voice card
  158. (`card.md` plus per-situation sheets) that any generating model follows in context.
  159. 1. **Harvest.** Cheap agents bootstrap the corpus from your chat transcripts and writing
  160. folders. Adapters read both Claude Code (`claude-jsonl`) and Codex CLI/Desktop
  161. (`codex-jsonl`) sessions, auto-detected by shape. The contamination guarantee is the whole
  162. point, because assistant-authored text in a voice profile would teach the exact register
  163. unslop removes. So the adapters drop assistant and developer turns, strip injected content
  164. like a
  165. dumped `AGENTS.md`, and run every kept candidate through the scanners. A hard hit or two
  166. scanner categories marks a sample `suspect_ai`, ranked last and never auto-approved. Nothing
  167. reaches a profile without your approval.
  168. 2. **Profile and card.** `voice_profile.py` computes the stylometric fingerprint (character
  169. 3-grams, function-word deltas, sentence-length distribution, punctuation, contractions,
  170. MTLD, impostor z-scores, GI rank). `voice_card.py` writes the layered card the generator
  171. reads. The card never fabricates, so a dimension with no sample evidence gets no sheet, and
  172. it's named under "Uncovered" instead. A profile that doesn't describe the supplied samples
  173. gets rejected (exit 2), so a stale profile can never drive a card.
  174. 3. **Calibrate.** When samples run thin, an A/B preference game gathers voice signal at
  175. tap-level effort. The pairs are dimension-controlled minimal edits of your own passages,
  176. mostly from deterministic transforms, so each pair keeps the passage's facts. Preferences
  177. aggregate per dimension with confidence bounds, and the game targets the least-known
  178. dimension next, while a stated preference that contradicts a sample-measured value surfaces
  179. to you as a named conflict, never resolved silently. Voice beats the default register guard,
  180. but only in the open.
  181. 4. **Scored demo.** teach closes by mimicking one paragraph, scoring it, and running the
  182. scanners in front of you. A voiced demo that trips a slop gate fails the loop.
  183. ### mimic
  184. `mimic` drafts or rewrites in the taught voice, then clears the full gate battery. The rule is
  185. absolute, so a mimic that scores well on voice but trips a removal gate gets rejected. Voice never
  186. buys an exemption from the constitution, and meaning preservation against the original draft
  187. is its own separate hard gate.
  188. - **Voice check** answers "does this sound like me?" with a score and no rewrite. It reports
  189. the composite (lower is more you), the General Impostors rank, and the two or three metric
  190. deltas that explain the score in plain words. It's the cheapest voice interaction and the
  191. usual one after teach. Check drafts often, commission rewrites rarely.
  192. - **Refine** hill-climbs when a single pass keeps landing short. It splits samples into a
  193. retrieval pool and a held-out acceptance split, generates candidates, and discards any that
  194. trip a hard gate (banned-phrase, structure, draft-to-candidate preservation, a copy-gate
  195. against the pool, and a word floor). Survivors get scored on the held-out split with a
  196. gaming-resistant composite: `0.5·(1−GI) + 0.5·` a clipped impostor-z distance against a
  197. same-genre impostor pool. A marker-stuffed candidate can drive a raw distance down and still
  198. lose under the General Impostors rank, and that's what stops it from beating honest prose. A
  199. **divergence guard** halts the loop and raises `reward_hacking_warning` when the pool score
  200. improves while the held-out score worsens for two iterations. Claim a win only when
  201. `mimic_stats.py` shows the confidence-interval lower bound above zero and p below 0.05.
  202. ## Co-writer: cleanup
  203. `cleanup` is the co-writer mode. On detection it surfaces findings as structured suggestions,
  204. never a silent rewrite. Each suggestion carries a span, severity, category, rationale, and
  205. proposed replacement. Detection is cheap and deterministic, and replacement generation is
  206. delegated to a stronger model, which fills in the null replacements the scanner leaves.
  207. Hard findings become direct replacements. Soft findings are register-dependent, so their
  208. rationale is phrased as a question rather than an edit. Four contract gates in
  209. `check_suggestions.py` make "accept all" safe by construction:
  210. - **span-minimality**: an edit changes only its own span, and a whole-sentence rewrite fails.
  211. - **replacement-scanner**: each replacement passes both scanners in isolation and adds no new
  212. violation in context.
  213. - **accept-all**: applying every suggestion yields a document that passes both scanners and
  214. preserves every constraint against the original.
  215. - **span-overlap**: spans may not overlap.
  216. A report-only variant ("flag it, change nothing") runs the scanners and reports each issue by
  217. span, category, and severity, separating clear problems from judgment calls.
  218. ## Contribute: the growth flywheel
  219. Detection catalogs decay as generators evolve. Growth comes from adversarial refresh, where a
  220. wild specimen becomes an eval row becomes a structured PR. `/unslop contribute` runs the
  221. pipeline offline until you approve publication.
  222. 1. **Precheck** tells you whether the tell is already covered.
  223. 2. **Confirmation gate one** shows you the exact snippet and asks whether it may go public,
  224. with redaction hints that keep the tell byte-for-byte intact.
  225. 3. **Scaffold and implement eval-first.** The false-negative row lands red before the scanner
  226. changes, and a literal-use false-positive row lands beside it. The scanner and catalog then
  227. change until the row goes green while the protection row holds.
  228. 4. **Verify** captures the red-to-green transition and refuses TODO markers.
  229. 5. **Full gate battery**, then **confirmation gate two** on the final PR body. Only then does
  230. the host agent branch, commit, and open the PR. The scripts never touch the network.
  231. Yesterday's miss becomes tomorrow's regression test, and nothing rides on good habits.
  232. ### Worked example
  233. The maintainer caught `"Four presets, one input."` on his own marketing page: a standalone
  234. section header in slogan cadence. Precheck against the catalog came back clean — nothing in
  235. `banned_phrase_scan.py` covered it yet, which is what made the specimen contributable.
  236. That miss became `OWNER-01`, and the row went red before any fix existed:
  237. ```json
  238. {
  239. "id": "OWNER-01",
  240. "stdin": "Four presets, one input.",
  241. "assertions": [
  242. { "type": "json", "path": "total_violations", "gte": 1 },
  243. { "type": "violation_category_equals", "value": "slogan_fragment" }
  244. ]
  245. }
  246. ```
  247. The fix is a new `slogan_fragment` entry in `STRUCTURAL_PATTERNS`:
  248. ```python
  249. r"(?:^|\n)[ \t]*(?:#{1,6}[ \t]*|>[ \t]*|[-*+][ \t]+)?(?:\*\*)?(?:one|two|three|four|five|six|"
  250. r"seven|eight|nine|ten|\d+)\s+[^,.!?\n]{1,40},\s+one\s+[^,.!?\n]{1,40}[.!?](?:\*\*)?[ \t]*(?=\n|$)"
  251. ```
  252. It's anchored to `^|\n` and `(?=\n|$)` on purpose: standalone headline position is the tell,
  253. not the "N X, one Y" shape by itself. `FP-86` proves `"The unit has two bedrooms, one bath, and
  254. a den."` stays clean, since the same words embedded mid-sentence never reach the line boundary.
  255. OWNER-01 went red to green the moment the pattern landed, FP-86 held green the whole time, and
  256. `slogan_fragment` now sits inside the blocking gate battery that runs on every push to this
  257. repo — the project's own site included.
  258. The pipeline that produced this row is itself eval-covered: the `CONTRIB-*` rows and the
  259. `contribute-suite` gate pin precheck, scaffold, and redaction behavior end to end, and a
  260. `SLUG-01` row pins path safety against a hostile `--pattern-name`.
  261. Caught a specimen but working outside an agent? [CONTRIBUTING.md](CONTRIBUTING.md) links the
  262. fast path and the manual path.
  263. ## The Eval Suite Is the Product
  264. The contracts remain constitutional, but repository checks are engineering evidence. They do
  265. not prove that UNSLOP improves prose.
  266. - **Fast core-contract loop.** `python3 evals/check.py` runs five offline examples covering the
  267. manifest, Luna runner interface, scorer, evidence boundaries, and acceptance gate.
  268. - **Bounded release suite.** `python3 evals/check.py --full` adds the deterministic safety and
  269. integrity matrix, generated-benchmark currency, and strict leakage validation. The suite is
  270. capped at 80 executable examples and 400 expanded outcome predicates, including predicates
  271. hidden inside Python fixtures. Nested aggregate wrappers fail the build.
  272. - **Compact scanner evidence.** Scanner, preservation, and maintenance examples live in
  273. explicit contract tables. Current coverage is 36/36 structural patterns, 16/16 literal
  274. triggers, and 20/20 protected categories, with zero expected failures.
  275. - **Behavioral layer.** `evals/shared-benchmark.json` is generated from 12 `skill` cases with
  276. three ablations. It is useful for shaping and regression checks, but it is not the core
  277. product scoreboard.
  278. The latest valid public core result remains the v9 no-ship recorded in
  279. [`evals/CORE-RESULTS.md`](evals/CORE-RESULTS.md). Later development runs are directionally
  280. favorable—Luna+UNSLOP recorded seven wins, four ties, and no plain-Luna wins—but they predate
  281. scorer and per-case efficiency fixes. A fresh preregistered corpus failed its composition floor
  282. before either arm ran. The current beta therefore does not claim a validated comparative lift.
  283. ```bash
  284. python3 evals/check.py # fast offline core-contract check
  285. python3 evals/check.py --full # bounded deterministic release suite
  286. python3 evals/run_adversarial.py --only FP # diagnose one failing category
  287. python3 evals/check.py --behavioral tune # core-contract + behavioral tune
  288. ```
  289. ## The Core Comparison Uses Luna
  290. The shipping question is paired and model-controlled: the same `gpt-5.6-luna` receives the
  291. same unfamiliar source in both arms. One arm gets the frozen UNSLOP diagnosis, rewrite, and
  292. validation pipeline; the other gets neutral editorial guidance without repository access,
  293. scanner output, or validation feedback. A blinded `gpt-5.6-sol` judge sees randomized arm
  294. labels. Calls, uncached input tokens, output tokens, and elapsed time are recorded per case.
  295. Older cross-provider model-parity tables remain in `references/pipeline.md` as ancillary
  296. engineering history. They are not acceptance evidence and do not replace the Luna-vs-Luna
  297. core comparison.
  298. ## Standalone Scripts
  299. The scripts run independently, standard library only. A quick tour:
  300. ```bash
  301. # Phrase, structure, and silhouette scans
  302. python3 scripts/banned_phrase_scan.py < input.txt
  303. python3 scripts/banned_phrase_scan.py --include-quoted < input.txt # audit quoted examples too
  304. python3 scripts/structure_scan.py < input.txt
  305. python3 scripts/structure_scan.py --genre docs < README.md # reference-doc carve-outs
  306. python3 scripts/silhouette_scan.py < input.txt # idea-arrangement tells
  307. # Facts and preservation
  308. python3 scripts/extract_constraints.py < input.txt
  309. python3 scripts/validate_preservation.py original.txt transformed.txt
  310. python3 scripts/validate_preservation.py --strict original.txt transformed.txt # regulated text
  311. python3 scripts/diff_check.py original.txt transformed.txt
  312. python3 scripts/readability_metrics.py < input.txt
  313. # Co-writer suggestions
  314. python3 scripts/suggest.py document.md
  315. python3 scripts/check_suggestions.py suggestions.json # the four contract gates
  316. # Voice
  317. python3 scripts/harvest_samples.py SOURCE -o candidates.json # bootstrap from transcripts
  318. python3 scripts/voice_profile.py samples/ -o profile.json # stylometric fingerprint
  319. python3 scripts/voice_card.py --profile profile.json --samples samples/ --out . --name me
  320. python3 scripts/voice_score.py --profile profile.json candidate.md # "does this sound like me?"
  321. python3 scripts/calibrate_pairs.py generate --base passage.txt --dimension em_dash --seed 1
  322. python3 scripts/wiki_sync.py check # sync the phrase catalog
  323. ```
  324. ## Project Structure
  325. ```
  326. unslop/
  327. ├── SKILL.md # Four-verb router and shared doctrine
  328. ├── README.md # This file
  329. ├── references/
  330. │ ├── commands/ # The routed flows: teach, cleanup, rewrite, mimic, contribute
  331. │ ├── taboo-phrases.md # Authoritative pattern catalog (all families)
  332. │ ├── mimic.md # Teach/mimic internals: card anatomy, scoring, refine
  333. │ ├── harvest.md # Adapter internals and the contamination tripwire
  334. │ ├── calibrate.md # The A/B preference game
  335. │ ├── core-contract.md # Single diagnosis, rewrite, and preservation contract
  336. │ ├── pipeline.md # Luna core protocol plus ancillary model-parity history
  337. │ ├── fact-preservation.md # Constraint preservation rules
  338. │ ├── rubric.md # Strict scoring criteria
  339. │ ├── edit-library.md # Transformation examples
  340. │ ├── personality-guide.md # Adding voice without fake personality
  341. │ ├── maintenance.md # Add/list/wiki-sync procedures (eval-first)
  342. │ └── packs/ # Small detector rule-packs plus manifest
  343. ├── presets/ # crisp / warm / expert / story voice deltas
  344. ├── scripts/ # Scanners, voice tools, preservation, suggest, harvest
  345. ├── evals/
  346. │ ├── adversarial-evals.json # Core plumbing, routing, and engineering rows
  347. │ ├── fixtures/contracts/ # Compact scanner, preservation, and maintenance examples
  348. │ ├── check.py # Fast and full bounded repository checks
  349. │ ├── run_adversarial.py # Deterministic runner (--only, --case, --list-gates)
  350. │ ├── shared-benchmark.json # Generated behavioral manifest (never hand-edit)
  351. │ ├── build_shared_benchmark.py # Regenerates the behavioral manifest
  352. │ ├── run_model_parity.py # Re-measures the tiering matrix
  353. │ ├── CHECKS.md # Canonical check and external gate surface
  354. │ └── check_*.py # Parity, doc, pack, voice, and silhouette gates
  355. ├── docs/
  356. │ └── PRODUCT.md # Product doctrine (the why behind the repo)
  357. └── assets/
  358. └── examples/ # Before/after sets: article, LinkedIn, sales
  359. ```
  360. ## Voice Presets
  361. Read one preset from `presets/` before a rewrite.
  362. | Preset | Style | Best for |
  363. |--------|-------|----------|
  364. | `crisp` | Short, direct, no filler | Technical writing, documentation |
  365. | `warm` | Friendly, conversational | Emails, blog posts |
  366. | `expert` | Authoritative, confident | Thought leadership, articles |
  367. | `story` | Narrative flow, show rather than tell | Case studies, personal posts |
  368. ## Scoring Rubric
  369. Eight criteria, one to five points each (40 maximum): directness, natural rhythm, concrete
  370. verbs, reader trust, human authenticity, content density, fact preservation, and template
  371. avoidance. Strict mode fails a rewrite scoring below 32/40. Criteria live in
  372. `references/rubric.md`.
  373. ## Supported Agents
  374. This skill follows the [Agent Skills specification](https://agentskills.io) and works with:
  375. - Claude Code
  376. - Cursor
  377. - Codex
  378. - OpenCode
  379. - Cline
  380. - Roo Code
  381. - And [35+ other agents](https://github.com/vercel-labs/skills#supported-agents)
  382. ## Wikipedia Sync
  383. Part of the phrase catalog derives from Wikipedia's
  384. [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) guide. The
  385. skill can sync itself with that page to pick up new patterns as editors add them:
  386. ```bash
  387. python3 scripts/wiki_sync.py check
  388. ```
  389. The sync diffs against the last run and proposes updates to `taboo-phrases.md` and the phrase
  390. scanner, always eval-row-first per `references/maintenance.md`. Wikipedia-only patterns (broken
  391. wikitext, DOI issues) get skipped, and state lives in `scripts/.wiki_sync_state.json`
  392. (gitignored).
  393. ## Maintenance
  394. All maintenance is eval-first, and the row lands red in `evals/adversarial-evals.json` before
  395. any scanner or catalog edit turns it green. `references/maintenance.md` holds the procedures for
  396. adding a banned phrase (with its required literal-use protection row), adding a structural
  397. pattern, listing current patterns, and running the Wikipedia sync. `CLAUDE.md` and `AGENTS.md`
  398. hold the contribution rules, and `docs/PRODUCT.md` holds the reasoning behind them.
  399. ## Philosophy
  400. AI text follows predictable patterns that readers learn to spot. unslop doesn't just swap
  401. words, it restructures content to read as human, and it refuses to fix writing that was never
  402. broken. The guiding principles:
  403. - **Cut what carries no meaning.** If removal doesn't change the meaning, remove it.
  404. - **Trust the reader.** They don't need `"let that sink in"`.
  405. - **Facts are sacred.** Numbers, names, dates, negations, and scope survive unchanged.
  406. - **Do no harm.** Register hedges, literal vocabulary, and already-human prose stay intact.
  407. - **Voice runs under the constitution.** A mimic that reintroduces slop is a failure.
  408. - **The eval suite defines the product.** If a behavior matters, a row fails without it.
  409. ## Requirements and License
  410. Python 3.8+ and any supported coding agent. Licensed MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.