Declauding

Declauding

Turn LLM-shaped prose into prose a human technical writer would have written.

Two output modes:

• clean (default) — the rewritten text, nothing else.
• annotated — a single-file HTML artifact: rewritten text, every changed passage marked, each with the original, the tic name, and why it goes. A toggle hides the marks so the result can be read straight through.

Three ways it gets called, which change what you deliver:

• Pasted text (default) — the user gives text in the conversation. Return the rewrite, plus a short list of what changed if the edit was substantial.
• File — the user points at a path. Rewrite the file in place and report a summary in the conversation rather than pasting the whole result back. Edit prose only: leave code blocks, frontmatter, data, link targets and quoted specimens alone.
• Embedded — another skill or agent is calling this as one step of a larger job (a PR description, a commit message, a doc). Return the final text and nothing else. No preamble, no summary, no tic list.

Do not invent specifics

The rewrite must not contain a fact, name, number, date, quote or citation that is not in the source. This is the failure mode the skill invites rather than prevents: the fix for a vague sentence is a specific one, and the specific has to come from the source or from the author.

Experts believe it plays a crucial role becomes the sources here do not say who studies it, or gets cut. It does not become researchers at Lanzhou University unless the source says so. When a sentence needs real-world detail to work, ask for it or write the plain version without it.

Opinions and stance count as voice rather than fact. Keeping the author's judgment is required (see Overcorrection); adding a factual claim they did not make is a defect even when the result reads more human.

The one pattern

Almost every tic in references/register.md is a version of the same move: the sentence is built to make the reader feel a finding arrive, instead of stating the finding.

The generative test, applied per sentence: am I saying the thing, or performing having had the thought? Say the thing.

The register has four families. Read the one the draft needs first.

The flat-certainty register is where a clean pass lands, and it is now the fastest-growing cluster of GitHub pull request descriptions: 0.70% of early 2025, 39.5% of August 2026 (references/corpus.md). Its test is the same one turned over: am I stating the finding, or performing having settled it? The fix is never to put the staging back. It is to check that the adverb, compound or negative carries evidence.

Model profiles

When you know which model wrote the draft, read its file in references/models/ before step 2. When you know which model you are, read your own file too. Each file has two sections: what to look for in that model's drafts, and what to check in your own rewrite when you are that model.

When Claude is cleaning its own draft, one file covers both sections; run step 2b in a subagent or separate context. When the author is unknown or human, skip the profiles.

On any model's draft, check the opening for a contents-list standfirst (entry 42): here's what happened, and what we should have measured.

Author's writing sample

If the user supplies a sample of their writing, read it before editing and match its habits: sentence lengths, paragraph openings, punctuation, recurring phrases, vocabulary level. Do not upgrade casual words, regularize deliberate quirks, or apply a register rule the sample contradicts.

The sample wins over every rule here, including the em-dash density guard in entry 16. If the author uses em dashes at three per hundred words, that is their voice, and scrubbing the tell would make the text less like them and no more human. The same holds for their existing published work when it is available and the current draft is not.

Workflow

Script paths below are relative to this skill's directory. From any other working directory, prefix them with /mnt/skills/user/declauding/.

1. Read the whole piece before editing anything. Tics carry factual errors. A sentence written to sound important is disproportionately likely to be wrong, because it was built for shape rather than for accuracy. Designations of the form the X that answers the real question frequently designate the wrong X, and the draft itself often contradicts them a paragraph later. Note contradictions now; they are the most valuable thing this pass produces.

2. Run the mechanical scan.

python3 scripts/declaude_lint.py DRAFT.md
python3 scripts/declaude_lint.py DRAFT.html               # HTML is flattened automatically
python3 scripts/declaude_lint.py DRAFT.md --skip-quoted   # if the draft quotes bad prose

It flags greppable tells with line numbers and categories, plus four shapes that are not lexical: forced triads in both their comma-list and anaphora forms, one-line-paragraph beats, fragment runs, and constructions the document uses more than once. The reuse block is the cheapest signal it produces, because a construction used twice is a habit and counting is free.

It has no judgment. Everything it flags still needs the sentence-level test, it reaches roughly two thirds of what a careful pass finds, and the third it misses is the expensive third: staged paragraph shape, staged closers, dressed metaphor, and every earned exception. Step 2b takes part of that third; the rest is yours. Treat a clean report as meaningless on its own, and expect one on Opus 5 drafts, which stage heavily in shapes the scan cannot see.

Use --skip-quoted on any draft that quotes bad prose as a specimen. Without it the scan reports the draft's own examples, which is how a real pass loses time.

HTML input is flattened before scanning: <h1>–<h6> become headings so the header rules see them, and a .subtitle, .eyebrow or .post-meta element is treated as a heading too, because a subtitle is a header by every test that matters. Force with --html, disable with --no-html. Reported line numbers refer to the flattened view.

The corpus-register density line locates a register. It does not detect an author. Above roughly 1.0 per 100 words the draft sits in the cluster's register, and a person who chooses that register scores there too, so the line is a cue to read entries 43 to 47 and never a licence to cut nothing or measured on sight. references/corpus.md has the figures.

Lint every string that reaches the reader, not only the body file. Page titles, subtitles and deck headers are prose, and a builder that takes them as CLI arguments rather than from the file will hide them from this scan.

2a. Optionally, rank the sentences.

python3 scripts/declaude_rank.py DRAFT.md --top 15

Sorts sentences by how staged they look, using a fitted direction in embedding space (the mean of embed(was) - embed(now) over the register's before/after pairs). It shortlists and decides nothing. On the one pass it was measured against it ranked all nine edited sentences at a median of 13 of 53, where the regex scan had found one of the nine. It cannot score documents. Needs torch and transformers; every other stage is standard library. references/preservation.md has the numbers.

2b. Run the structural review.

python3 scripts/declaude_review.py DRAFT.md

This is the third the scan cannot reach. It extracts the slots regex cannot judge — every header, the opening sentence, each closing sentence, isolated one-sentence paragraphs — and sends only those to a model with the structural entries from references/register.md. Slots rather than the whole document, because the payload stays small enough to run on every draft. Use --emit-prompt where no API key is available, --slots to see the extraction alone.

The two stages do not subsume each other. Stage 1 finds the flat verdict header deterministically and over-flags commas, including the ones that belong to a citation. Stage 2 reads a comma in context and finds the aphoristic closer, which no regex reaches. Run both.

Run stage 2 in a context that did not write the draft. A model reviewing its own prose is the actor that chose the words. With --emit-prompt: if you did not write the draft, answer the prompt yourself; if you did, hand it to a subagent. If you wrote it and cannot spawn one, answer it anyway and say in your report that the review was not independent.

For a full-document register review against a named voice signature — positive markers, drift across the piece, imposter test — use the challenging skill's prose-register profile instead. This script is the cheap pass; that one is the thorough one.

3. Sentence pass. For every sentence, in order: stating or staging? Load references/register.md for the catalogue of tells and their fixes, and references/exceptions.md before deleting any flagged shape — it lists when each shape carries a claim. Start with the family the draft needs: the author model's profile names it; on a draft this skill or another model already cleaned, read 43 to 47 first; on a personal essay, a launch post, or anything addressed to the reader as a confidant, read 48 to 52 first.

4. Structure pass. Headers (are they labels or verdicts?), paragraph breaks (is an isolated line a real pivot or a drum roll?), fragment runs, rhetorical questions, and the closer (does the last paragraph paraphrase the subtext of what preceded it? delete it).

5. Check what the edit did.

python3 scripts/declaude_diff.py SOURCE.md REWRITE.md
python3 scripts/declaude_diff.py --git path/to/draft.html --ref HEAD

Run this before reporting the pass done. It compares source against rewrite for numbers, names, quotations, code and link targets by presence, and for superlative, scope, negation and hedge constructions by count, and reports what the edit lost and what it invented. Constructions rather than tokens, because rewriting "the format that most invites staged reveals" as "more than most formats do" keeps the word and drops the ranking.

An embedding similarity does not substitute for it: on the three real cases in references/preservation.md the lossy rewrite scores higher cosine to the source than the faithful one. Paraphrase invariance is what an encoder is trained for, and dropping a ranking word is a paraphrase by that measure.

The script guards claims and not voice, and a finding is a question rather than a verdict — a rephrasing it cannot see through takes a --waive. Four failure modes, all of them common:

• Content lost. Ask it as a question and answer it claim by claim, not paragraph by paragraph: does the rewrite drop a claim the source made? A dropped superlative leaves the paragraph looking intact, which is why the read-through misses it. Every fact, number, caveat and hedge-with-content must survive; a tic wrapping a real qualification is still a real qualification. See Earned exceptions for what hides inside a watched phrase. Structure is free — merge or split paragraphs, compress the dull parts, dwell where the author would. When keeping the information and mirroring the original's shape pull against each other, the information wins.
• Claims changed. Rewriting "the drop is largest where chains are longest" into "long chains cause the drop" is an edit that invents a finding. Register only.
• Facts invented. Ask it directly: does the rewrite state any name, number, date or citation that is not in the source? See "Do not invent specifics" above.
• Mush. See Overcorrection below.

6. Report factual problems separately. Never silently fix a contradiction found while editing. The author needs to know their draft disagreed with itself, and only they can say which version is true.