Text humanizer

Text Humanizer

Make enterprise text read as if a competent person wrote it. That is two jobs: removing AI tells, and replacing them with prose that is concrete and pitched to the right register. Text that is merely "clean" still gives itself away when it is voiceless, evenly paced, and hedged on every point. This is not a game against detectors; never bend facts, terminology, or meaning to make a sentence flow.

Applies to new content, rewrites, and in-place editing across documentation, design docs, API references, reports, executive summaries, status updates, emails, and blog posts.

Two layers matter, and most work neglects the second. The surface layer is vocabulary, punctuation, and rhythm: worth fixing, but shallow, and newer models plus one editing pass wash most of it out. The structural layer is what the document names, whether it explains its own point, whether it resolves tension it never earned, and how it is shaped. That layer separates human from machine writing and word-swaps leave it untouched. Weight the effort there.

Workflow Router

Determine the task mode and document type before editing. These drive which phases apply and how much voice to add.

What is the task?
  |
  +-> Rewrite or de-AI an existing draft
  |     --> REWRITE mode
  |     Phases: Classify -> (Calibrate) -> Detect -> Rewrite -> Audit -> Verify
  |
  +-> Edit an existing file in place (surgical, preserve structure)
  |     --> EDIT-IN-PLACE mode
  |     Phases: Classify -> (Calibrate) -> Detect -> Rewrite (minimal diff) -> Audit (changed lines) -> Verify
  |
  +-> Write new content that must not read as AI-generated
  |     --> AUTHOR mode
  |     Phases: Classify -> (Calibrate) -> Draft -> Audit -> Verify
  |
  +-> Only assess / score how AI-sounding text is (no rewrite requested)
        --> DETECT-ONLY mode
        Phases: Classify -> Detect -> Report (cluster findings, no rewrite)

Calibrate runs only when the user supplies a writing sample to match. Otherwise skip it and use the register default for the document type.

Signal detection:

Signal in request	Mode
"humanize", "de-AI", "make this sound human", "rewrite this"	Rewrite
"edit the file", "fix the README", "clean up this doc" (a file path given)	Edit-in-place
"write a", "draft a", "create a" (and it must sound human)	Author
"does this sound AI", "check this", "how AI-sounding is this"	Detect-only

Document Type and Register

Classify the document type, then set the register before touching anything. The most common failure is over-correction: turning a precise API reference into chatty prose, or injecting first-person opinions into a legal document.

Document type	Default register	Personality?
Technical design doc	Neutral, precise; assumptions and trade-offs stated	Opinionated rationale only
API / reference docs	Strictly neutral, imperative, present tense	None
Architecture / explanation	Neutral, explanatory	A clear stance on decisions
Executive summary	Formal, plain, BLUF, quantified	Minimal
Status report	Plain, scannable, factual	Honest risk framing
Internal email	Conversational, direct	Yes
Customer-facing email	Warm but professional	Yes, specific not generic
Blog post / thought leadership	Conversational, opinionated	Yes, most of all
Legal / compliance / policy	Formal, exact, conservative	None

"Human voice" does not mean "casual voice." For API docs, legal text, and formal specs, neutral and plain is the human voice. For blogs, emails, and design rationale, sterile prose is itself a tell and voice should be added. See references/register-guide.md for the full matrix, the personality decision, and voice calibration.

Core Principle

Optimize for clarity and information density, not for sounding smart or polished. If a sentence exists mainly because it sounds good rather than because it carries information, cut it. The full editing standards live in references/enterprise-standards.md.

---

Phase 1: Classify

Establish three things before editing:

1. Task mode (from the Workflow Router).
2. Document type and register (from the table above). When unclear, infer from the content and existing formatting; ask the user only if genuinely ambiguous.
3. House conventions (for Edit-in-place and brownfield docs): heading case, code-block style, terminology, whether bold defined terms and bullet lists are already the norm. Match these. Do not impose new conventions as a drive-by change.

Phase 2: Calibrate (Optional)

If the user supplied a writing sample, analyze it before rewriting and match its sentence rhythm, word-choice level, and habits. See the Voice Calibration section of references/register-guide.md. With no sample, use the register default for the document type.

Phase 3: Detect

Scan the text against the full catalog in references/pattern-catalog.md (42 numbered patterns across content, language, style, communication, filler, cadence, and discourse). Use references/word-lists.md for fast grep-able passes over AI vocabulary, jargon, filler, opening clichés, chatbot artifacts, and markup leakage.

Run two passes, surface then discourse. The word-lists and most of the catalog catch surface tells: vocabulary, punctuation, sentence rhythm. Do that pass first. Then step back and read the whole document for the four discourse tells (patterns 39-42), which no grep finds:

• Over-determination (39): does it explain its own point, add a takeaway, or moralize where the fact already carried the meaning?
• Generic where a human names specifics (40): does it gesture at "a framework," "the relevant docs," "best practices" where a person would name the actual thing?
• Manufactured closure (41): is every risk instantly mitigated and every question resolved, with no honest open item?
• Default skeleton (42): restating intro, evenly weighted sections, a recap that adds nothing, an order that could be shuffled without loss?

These matter most because they survive surface editing. Fixing vocabulary and dashes without fixing structure leaves the strongest tells in place.

Judge by cluster, not by isolated hits. A single em dash, one transition word, or formal vocabulary alone is not evidence. A cluster is: em dashes plus rule-of-three plus "vibrant tapestry" plus a "Challenges" section. Before rewriting, confirm you are not gutting legitimate prose. Review the "What NOT to flag" and "Signs of human writing" sections of the pattern catalog.

Note the specific patterns present so the rewrite is targeted, not a blind reflow.

Phase 4: Rewrite (or Draft, in Author mode)

Produce a draft that fixes the detected patterns and meets the enterprise standards in references/enterprise-standards.md.

Apply, in roughly this order:

1. Cut the AI tells found in Detect: marketing adjectives, AI vocabulary, significance inflation, copula avoidance, filler, hedging, chatbot artifacts, markup leakage.
2. Replace vague claims with specifics. Every qualitative descriptor becomes a number or a concrete observation. This is the highest-impact move. Never fabricate a figure. If unknown, say what is known and what is not.
3. Take a position where the evidence supports one. Remove false balance and symmetric hedging. Name the trade-off you accept.
4. Remove em dashes and en dashes (hard constraint). Replace with periods, commas, colons, or parentheses.
5. Vary sentence length deliberately (pattern 34). This is a required structural edit. After the word-level rewrite, read the draft and check the cadence. If most sentences are within a few words of each other, merge some and split others into a real mix of short, medium, and long.
6. Give the piece a spine (pattern 35). Cut paragraphs that only re-summarize. Use connectives that signal real logical dependence, not additive filler.
7. Fix the discourse tells (patterns 39-42, defined in Phase 3), the structural half word-swaps miss.
8. Preserve meaning, terminology, and coverage. If the original has five sections, the rewrite has five. Do not drop technical precision to make prose flow.
9. Stay in register. Add voice only where the document type calls for it (Phase 1). Do not casualize reference, legal, or formal specs.

Edit-in-place mode: apply changes surgically. Minimize the diff. Fix the AI patterns; leave correct, in-register content alone. Do not restructure or restyle sections outside the AI-pattern fixes.

Phase 5: Audit

Ask explicitly: "What still makes this read as AI-generated?" Answer in a few brief bullets (lingering even cadence, a slogan-y closer, any remaining hedge or adjective, placeholder-sounding specifics). Then produce a final rewrite that addresses them.

This second pass reliably catches tells the first draft misses. Do not skip it.

Edit-in-place mode runs a narrower audit: re-read only the lines you changed and confirm the replacement prose does not introduce new tells. A surgical fix can still drop an even-cadence or slogan-y sentence into the diff.

Phase 6: Verify

Run the final text through this checklist:

• No em or en dashes. Scan for —, –, and --. Any hit means not done.
• No markup or citation leakage (oaicite, contentReference, turn0search, stray utm_source=, placeholder text).
• No chatbot artifacts or sycophancy ("I hope this helps", "Great question").
• Sentence length varies. Not a uniform mid-length cadence.
• Claims are specific. Vague descriptors replaced with numbers or observations; no fabricated figures. Real referents named where the draft was generic (pattern 40).
• No over-determination or manufactured closure. The point is stated once, not re-explained (pattern 39); genuine open questions and accepted risks survive (pattern 41).
• Structure follows content. Section weights match where the substance is, not a default skeleton (pattern 42).
• A position is taken where evidence supports one; no symmetric false balance.
• Register matches the document type. Reference/legal stayed neutral; blog/email has voice if appropriate.
• Meaning, terminology, and coverage preserved. Nothing factual altered or dropped.
• House conventions intact (Edit-in-place): headings, code style, terminology unchanged except for the targeted fixes.

Deliverable

• Rewrite mode: the draft, the brief "still-AI" audit bullets, the final rewrite, and a short summary of what changed.
• Edit-in-place mode: the edited file (minimal diff) and a summary of changes.
• Author mode: the final text and the audit bullets that informed it.
• Detect-only mode: a findings report listing the clustered patterns present, with the most telling examples quoted. No rewrite.

Note: write directly to disk in a streaming/incremental fashion using multiple Edit/Write calls rather than one mega-write.

Worked Example (Rewrite mode)

A status-report paragraph showing the full loop.

Input (AI-sounding):

Our team has been leveraging a robust new caching solution to significantly enhance performance. This represents a pivotal step in our ongoing journey toward operational excellence — delivering faster, more reliable, and more scalable experiences for our users. While challenges remain, the future looks bright.

Draft rewrite:

We added a Redis cache in front of the product-catalog service this sprint. It cut median page-load time from 900 ms to 220 ms. Read traffic to Postgres dropped by about 70%, which also eased the connection-pool pressure that caused two incidents last quarter. One open issue: cache invalidation on price updates lags by up to 30 seconds, so we are moving to event-based invalidation next sprint.

What still reads as AI?

• Cadence is fairly even; could open with a shorter sentence.
• "eased the connection-pool pressure" is slightly soft; the incident detail carries it, so it is fine to keep.

Final rewrite:

We shipped a Redis cache for the product-catalog service this sprint. Median page-load time dropped from 900 ms to 220 ms, and read traffic to Postgres fell about 70%. That removed the connection-pool exhaustion behind two incidents last quarter. One thing is still open: price-update invalidation lags by up to 30 seconds. Event-based invalidation is the fix, and it is scheduled for next sprint.

The rewrite cuts the AI vocabulary and rule-of-three triad, drops the em dash and upbeat closer, replaces every vague claim with a measured figure, and names the open problem instead of "challenges remain."

Worked Example (Discourse patterns)

The surface-tell example above has clean vocabulary but can still fail on structure. This one has no AI vocabulary, no em dashes, and even grammar, yet reads as machine writing because of patterns 39-42. It is a design-doc excerpt.

Input (surface-clean, structurally AI):

We evaluated three options for the queue and chose a managed one. This decision demonstrates the importance of balancing cost against operational burden, a principle that guides good architecture. The managed option carries some risk, but with careful monitoring and a solid rollback plan, we are confident it will serve the team well. In summary, the managed queue is the right call.

Audit (what reads as AI, by pattern):

• Over-determination (39): "demonstrates the importance of... a principle that guides good architecture" and the "In summary" sentence both explain and restate a point already made.
• Generic (40): "three options," "a managed one," "some risk" name nothing. Which options? Which service? Which risk?
• Manufactured closure (41): "with careful monitoring... we are confident" tidies away a risk instead of stating it.

Final rewrite:

We chose Amazon SQS over self-hosted RabbitMQ and NATS. SQS costs about 15% more at our volume (~2M messages/day) but removes the broker on-call load, which cost us roughly a day per week during the RabbitMQ incidents in Q1. One risk is unresolved: SQS caps message size at 256 KB, and three of our event types exceed that today. We need the payload-offload-to-S3 pattern in place before cutover, and that work is not yet scheduled.

No vocabulary or punctuation needed fixing here; every tell was structural (39-41).

---

Failure Recovery

Problem
  |
  +-> Rewriting would strip required technical terms or precision
  |     +-> Keep the terms. Humanizing never lowers accuracy.
  |     +-> Vary the prose around the terms instead.
  |
  +-> Unsure whether a pattern is an AI tell or legitimate house style
  |     +-> Check the cluster. Isolated hits in formal docs are usually fine.
  |     +-> Match the existing document's conventions; do not impose new ones.
  |
  +-> The text has no figures and every claim is vague
  |     +-> Do not invent numbers. Ask the user for data, or state the claim
  |         plainly and flag that it is unquantified.
  |
  +-> Tempted to casualize a reference, legal, or spec document
  |     +-> Stop. Plain and neutral IS the human voice there. Only remove tells.
  |
  +-> Draft still reads AI after one pass
        +-> The tells left are almost always structural, not lexical. Run the Audit
            phase on cadence (34), argument spine (35), and the discourse tells
            (39-42, defined in Phase 3). Word-swaps do not touch these.

Never fabricate specifics. Replacing a vague claim with a made-up number is worse than leaving it vague. When data is missing, say so.

Never alter meaning. Humanizing changes how something reads, not what it says.

---

Reference Files

• references/pattern-catalog.md — all 42 numbered patterns with before/after rewrites, plus detection guidance.
• references/enterprise-standards.md — quantification, assumptions, positions, BLUF, punctuation, editing-pass checklist.
• references/register-guide.md — document-type register matrix, the personality decision, voice calibration.
• references/word-lists.md — grep-able lists of AI vocabulary, jargon, filler, clichés, chatbot artifacts, and markup leakage, with replacements.