# Humanize Without Changing Facts

> Use when AI-written prose (articles, emails, docs, captions) needs to read like a person wrote it while its facts stay put. Runs an editor pass over prose only, then rejects edits that change per-citation numbers, double-quoted spans, links, code, citation placement or structure, or that a separate judge model says changed the meaning.

- Skill: `satisfying-systems/humanize-without-changing-facts` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add satisfying-systems/humanize-without-changing-facts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/satisfying-systems/humanize-without-changing-facts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: satisfying-systems (https://skillmd.com/u/satisfying-systems)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/satisfying-systems/humanize-without-changing-facts

---


# Humanize without changing facts

AI-written prose often reads as machine output even when the writer was told how to sound: aphoristic closers, "it's not X, it's Y", no contractions, every paragraph the same length. Tweaking the writer's prompt rarely fixes it. A separate editor pass does. But an editor that rewrites freely can also quietly change facts, so its safety has to be structural, not a matter of trusting the model.

The pattern: the editor rewrites prose, a deterministic checker compares the fact-bearing tokens of before and after, a different model judges whether the meaning changed, and any failure means you **keep the original text**.

## When to use it

- Long-form content with figures, prices, quotes or citations: articles, guides, reports.
- Outbound copy people will read: email drafts, outreach, social captions, site copy.
- Anywhere a later fact-check or reviewer should judge the text readers will actually see.

Skip it for legal text, quoted material you have to reproduce verbatim, and code comments.

## Procedure

1. **Separate prose from facts.** If the content is structured (JSON, front matter, a CMS record), pick out the prose fields, such as body paragraphs and summaries. Titles, slugs, claim lists, source lists and metadata stay untouched. When you merge back, take only those whitelisted prose fields from the edit and everything else from the original.
2. **Run the editor** with [references/editor-prompt.md](references/editor-prompt.md) on the prose. Write its output to a *new* file. Never overwrite the original.
3. **Check the invariants:**
   ```bash
   python3 scripts/check_invariants.py original.md edited.md --json \
     --keep "Product Name" --keep "Brand Inc." --word-band 0.85-1.15
   ```
   Exit 0 means all invariants hold, 1 means there's a violation (each one comes with a reason code), and 2 means a usage or IO error. It refuses to compare a file with itself, including through a hard link.
4. **Judge equivalence** with a different model or role from the editor, using [references/equivalence-prompt.md](references/equivalence-prompt.md). Compare original and edited section by section. Accept only the exact reply `{"changes": []}`.
5. **Decide.** Use the edited text only if steps 3 and 4 both pass. Otherwise keep the original and log the reason codes. A failed edit never fails the whole run, and you never ship a "best effort" edit.
6. **Run your normal gates afterwards** (fact check, critic, privacy check) on whichever text won, so they judge exactly what readers will see.

## What the checker enforces

| Code | Rule |
|---|---|
| `NUMBERS_PER_SPAN` | The text is split at citation markers (default `[C1]`, `[C1][C2]`, `[S3]`; set your own with `--cite-pattern`). Each span keeps the same numbers in the same order, and the sequence of marker groups is identical. With no markers, the whole text is one span. Covers currency, percentages, decimals, thousands separators (including space-grouped ones like `1 000`, with a regular, no-break, narrow no-break or thin space), ranges and times. |
| `CITATION_PLACEMENT` | Each marker group stays in the same paragraph or list item, counted by index within its section. Moving a marker within its own paragraph is allowed, as long as the numbers per span still match. |
| `QUOTES_EQUAL` | The multiset of double-quoted spans (straight and curly) is *equal*, and so is the count of each quote character. |
| `LINKS_EQUAL` | URLs, inline link targets and titles, emails, @handles and #hashtags are the same, in the same order. Reference definitions aren't parsed at all: each one is locked as a block, from its `[label]:` line through every following line up to a blank line or the start of a heading, fence, list item or another definition, and the blocks must be byte-identical apart from trailing whitespace. |
| `CODE_EQUAL` | Inline code and fenced blocks are byte-identical, in the same order. |
| `STRUCTURE` | Same heading levels in the same order, and the same number of paragraphs, list items and table rows in each section. |
| `KEEP_LITERALS` | Each `--keep` literal appears exactly as many times as before. Use it for names, product terms and anything else the editor mustn't touch. |
| `WORD_BAND` | The edited word count stays within the band (default 0.85–1.15 of the original). |

## Rules, and why

- **Check for equality, not preservation.** An "everything original is still there" check lets the editor *add* a fabricated quote or link. Equal multisets catch additions as well as removals.
- **Bind numbers to their citation span, in order.** A global set of numbers survives two prices being swapped between items. An ordered list per span doesn't.
- **Keep the marker sequence and placement fixed.** Moving a citation onto different advice changes what the source supports, even when every number stays put. Within one paragraph the checker can't tell which claim a marker supports, so that's left to the judge.
- **Have a different model judge meaning.** Rewording can move a fact between subjects ("two" becomes "three", a quality moves to another product) in ways no token check sees. A second role that didn't write the edit is the backstop.
- **Make the judge fail closed.** Accept one exact reply shape. Duplicate keys, extra keys, malformed JSON, a timeout or any exception count as "changed". A permissive parser turns a confused judge into an approval.
- **Keep the original on any failure.** The editor is an improvement, not a dependency. Dropping a good edit costs a little polish; shipping a bad one costs a fact.
- **Lock what you can't parse, and leave unprotectable markup alone.** Reference definitions are compared as byte-locked blocks instead of being parsed, because every syntax rule you encode is one an edge case can slip past. If your content has constructs the checker doesn't cover (raw HTML, indented code blocks), keep those fields out of the editor rather than adding a regex per construct.
- **Keep the checker linear.** Inline links are found by a single-pass scanner, and the remaining patterns run on short per-line or per-token slices. A backtracking regex over the whole text can make a hostile input hang the check.
- **Measure before loosening.** If too many edits get discarded, find which reason code dominates on real content before changing anything. Loosen one measured class at a time, and never by turning a check off.
- **Humanize before the fact gates, not after.** If fact checks run first, readers get text nobody checked.
- **Write to a new path.** An editor or wrapper that writes its output over the input destroys the evidence you compare against. Refuse an existing output path, refuse anything that's the same file as the input (hard links included), and write through a temp file plus an atomic rename.
- **Skip the "does this sound human" classifier.** It's an open-ended judgment with no stable answer, so it'll churn. Fix the known patterns in the editor prompt and keep the checks about facts.

## Limits

The checker is deliberately strict and deliberately narrow:

- It doesn't understand number words ("two" vs "three"), dates written out in words, or claims without numbers, and it can't tell which subject a number or claim belongs to inside a sentence. That's the equivalence judge's job.
- It treats a reformatted number (`9am` to `9 a.m.`, `3-5` to `3 to 5`) as a change. Tell the editor to keep numbers exactly as written.
- It recognises ATX headings (`#`) only, plus fenced code (backticks or tildes). Setext headings, indented code and raw HTML aren't protected structurally, so keep content like that out of the editor or add `--keep` literals for it.
- Two numbers separated by a single space where the second has exactly three digits (`in 2019 100 people`) count as one space-grouped number. Both texts are read the same way, so this only matters if the editor splits or joins them.
- When an inline link starting at `](` can't be parsed (unterminated, malformed, a blank line, or nesting deeper than 32), the raw text from that `](` to the end of its line is locked and compared byte-for-byte under `LINKS_EQUAL` instead of being skipped.
- Short texts have little room inside the word band. For a two-sentence caption, widen the band rather than skip the check.

## Files

- [references/editor-prompt.md](references/editor-prompt.md): the rewrite prompt.
- [references/equivalence-prompt.md](references/equivalence-prompt.md): the judge prompt, its exact reply schema, and a strict parser.
- [scripts/check_invariants.py](scripts/check_invariants.py): the invariant checker (Python 3.8+, standard library only).
- [tests/test_check_invariants.py](tests/test_check_invariants.py): run with `python3 -m unittest discover -s skills/humanize-without-changing-facts/tests` from the repo root.

