Humanize

Detect and remove AI writing indicators from documentation and prose. Transforms AI-generated text into natural, human-sounding writing while preserving technical accuracy.

Quick Start

Scan a file for AI indicators

python3 /home/ubuntu/skills/humanize/scripts/detect.py README.md

Auto-fix high-confidence issues

python3 /home/ubuntu/skills/humanize/scripts/detect.py README.md --fix

Scan an entire docs directory

python3 /home/ubuntu/skills/humanize/scripts/detect.py docs/ --recursive

Get JSON report for programmatic use

python3 /home/ubuntu/skills/humanize/scripts/detect.py README.md --json

Detection Patterns

The detector identifies 15 categories of AI writing indicators, each with a confidence score that determines whether to auto-fix, suggest, or flag for review.

Pattern	Confidence	Action	Example
AI attribution	1.00	Auto-fix	"Claude generated this" → remove
Em-dashes	0.95	Auto-fix	"critical—and important—feature" → commas
Redundancy	0.95	Auto-fix	"advance planning" → "planning"
Corporate jargon	0.90	Auto-fix	"leverage" → "use"
Buzzword clusters	0.90	Auto-fix	3+ buzzwords in one sentence
Stiff construction	0.90	Auto-fix	"It is important to note that" → remove
We→I conversion	0.90	Suggest	"We implemented" → "I implemented"
Passive voice	0.85	Suggest	"is processed by" → active voice
Formal metadata	0.85	Suggest	"This document provides" → remove
Hedge phrases	0.80	Suggest	"might potentially" → be direct
Acronym expansion	0.80	Suggest	"JWT" → "JSON Web Tokens (JWT)"
Transition phrases	0.75	Suggest	"Furthermore," → remove or simplify
Excessive dates	0.75	Flag	Timestamps in narrative prose
Over-structuring	0.70	Flag	Numbered lists for 2-3 items

Confidence thresholds: >= 0.90 auto-fix, 0.70-0.89 suggest with preview, < 0.70 flag for human review.

Workflow

Phase 1: Scan

Run the detector on target files. It skips code blocks, frontmatter, headings, and table rows automatically. The output groups findings by category and shows before/after previews.

Phase 2: Fix

Auto-fix applies to high-confidence patterns where the replacement is unambiguous. The script preserves leading whitespace and line structure. Use --output to write to a new file instead of overwriting.

Manual review is needed for suggestions and flags. For each suggestion, the report shows the line number, matched pattern, and proposed fix. Apply judgment — not every passive voice sentence needs rewriting, and some "we" usage is intentional.

Phase 3: Verify

After fixing, re-run the detector to confirm the count dropped. Read the output to make sure meaning was preserved. Technical specifications, API schemas, and code examples should never be modified.

Jargon Replacement Dictionary

When manually humanizing text beyond what the script catches, use these replacements:

AI Buzzword	Plain Alternative
leverage	use
utilize	use
robust	reliable, strong
seamless	smooth
ecosystem	system, tools
paradigm	approach
synergy	cooperation
innovative	new
cutting-edge	modern
empower	enable, help
holistic	complete
optimize	improve
scalable	flexible, can grow
streamline	simplify
facilitate	help
delve	explore
actionable	practical
impactful	effective

Rules

1. Never change meaning. Preserve intent, facts, and technical accuracy.
2. Never modify code blocks. Code examples, configs, and commands are untouched.
3. Never remove real attribution. Only remove AI attribution ("Claude", "the assistant").
4. Always preview changes. Show before/after diffs for transparency.
5. Always back up first. Copy originals before bulk operations.
6. Context matters for we→I. Keep "we" in team docs, user instructions ("we recommend"), and inclusive language. Convert only in solo developer contexts.