my-humanizer-es-en

---
name: my-humanizer-es-en
description: >-
  Humanize AI-flagged academic/professional text in Spanish and English so it
  passes stylometric AI detectors (Compilatio Magister+, GPTZero, Turnitin,
  Originality.ai) while keeping the original meaning, data, and citations intact.
  Use when the user says "humanize", "humanizar", "bajar el porcentaje de IA",
  "pasar Compilatio/Turnitin", "reduce AI score", "sounds like AI", "de-AI",
  "parafrasear las secciones en azul", or hands over a detector report (PDF) with
  highlighted passages plus a .docx/.txt to fix. Works iteratively: analyze the
  report, rewrite only the flagged passages, rebuild the document, repeat.
---

# my-humanizer-es-en — Humanizador definitivo ES/EN

Battle-tested pipeline that took a real academic article from **50% → 13% AI**
on Compilatio Magister+ across three iterations, without touching a single
citation or datum. This skill encodes exactly what worked.

Core idea: modern detectors (Compilatio, Turnitin, GPTZero) are **stylometric**,
not plagiarism-style. They flag *rhythm and structure*, not vocabulary. The win
comes from breaking AI's uniform cadence — above all, the `statement: elaboration`
colon habit and symmetric enumerations — and injecting real human burstiness.

---

## 0. When to use / what you get

Use when the user wants to lower an AI-detection score on a document, or fix the
"blue" (AI) and "similarity" sections of a detector report.

Two entry modes — **both fully supported**:
- **Report-driven** (best): a detector PDF report + the document. Extract the
  highlighted passages (§4), rewrite *only* those, iterate. Most efficient; this
  is what got 13%.
- **Blind** (no report): only the document. Run the internal leak scan (§4b) to
  find the passages most likely to trip a detector, rewrite them with the
  rulebook (§5), measure metrics (§7), deliver. Slightly less surgical than
  report-driven, but works with nothing but the text.

If the user has a detector report, ask for it — it makes every pass cheaper and
more precise. If they don't, or can't run the detector, go blind; never block on
the report.

Non-negotiable constraints:
- **Preserve the content core** — every claim, number, %, date, and citation.
- **Never alter the reference list.** Similarity hits there are legitimate
  citation matches; changing an APA/IEEE entry is an error, not a fix.
- **Preserve document structure** — headings, paragraph count, styles.

---

## 1. Prerequisites (install once)

```bash
python3 -m pip install --quiet pymupdf pypdf defusedxml
# docx read/write uses only stdlib + unix zip/unzip. LibreOffice optional (render check).
```

`pymupdf` (fitz) is the key tool: it reads the **highlight/underline fill colors**
in a detector PDF, which plain text extraction (pypdf/pdftotext) throws away.

---

## 2. Pipeline overview

```
extract text ─► (if report) parse highlights by color ─► classify passages
   ─► rewrite flagged prose (rulebook §5) ─► rebuild .docx (§6)
   ─► measure metrics (§7) ─► iterate on remaining flags (§8)
```

---

## 3. Read the document (.docx)

`pandoc` is often absent. Extract text directly from the XML — robust and
dependency-free:

```bash
unzip -q -o input.docx -d unpacked/
find unpacked -type l -delete            # untrusted docx: strip symlinks
```

```python
# scripts: quick paragraph dump
import re
x = open('unpacked/word/document.xml', encoding='utf-8').read()
paras = re.findall(r'<w:p\b.*?</w:p>', x, re.S)
for i, p in enumerate(paras):
    t = ''.join(re.findall(r'<w:t[^>]*>(.*?)</w:t>', p, re.S))
    if t.strip():
        print(i, t)
```

Note the **paragraph index** of every body block. Indices are the addressing
scheme for surgical rewrites and stay stable as long as you don't add/remove
paragraphs. Headings, abstract, keywords and the reference list are paragraphs
too — know which is which.

---

## 4. Parse the detector report (the decisive step)

Detector PDFs underline/highlight suspect text in color. Compilatio uses a
**thin colored underline** (~1.4pt rect) under each word:

- **Blue `#00beff`** = AI-detected passage → *must be paraphrased/humanized*.
- **Green `#cdf0ce` / `#58da5e`** = similarity to a source → *only correct if it
  is in the body*; in the reference list it is legitimate and left alone.

Run `scripts/analyze_report.py report.pdf` — it prints, per page, the exact text
sitting under blue underlines (IA) and under green (similarity). Because the
underline is a baseline strip, the script inflates each rect upward ~11pt and
tests bbox intersection with each word.

Colors vary by tool/version. If nothing maps, dump the fill-color histogram first
(the script does this with `--colors`) and identify the highlight color, then
pass `--blue RRGGBB`.

Only rewrite passages the report actually flags. Leave clean passages untouched —
re-touching them wastes effort and can *introduce* new patterns.

---

## 4b. Blind mode — internal leak scan (no report needed)

When there is no detector report, approximate one. Run:

```bash
python3 scripts/scan_leaks.py unpacked/ <body_indices>   # or --text file.txt
```

`scan_leaks.py` scores every sentence for stylometric AI tells (ES + EN) and
ranks the worst offenders, each with the reason it was flagged:

- very long sentences (low burstiness),
- `statement: elaboration` colons and colon-introduced lists,
- symmetric enumerations / rule-of-three,
- negative parallelism (`no solo… sino` / `not only… but`),
- AI vocab (`además`, `crucial`, `panorama`, `furthermore`, `delve`, …),
- em/en dashes, participle tails (`…-ando/-ing` giving false depth).

Treat its output like a detector's blue highlights: rewrite the top-scoring
sentences first (§5), re-run the scan, repeat until the flagged share and the §7
metrics look human. **It is a heuristic proxy, not a detector** — it finds
candidates, it does not certify a score. Combine it with §7 metrics; when the
two agree the text is clean, you are in good shape.

Reference point: after reaching 13% on Compilatio, the scan still marked ~16% of
sentences — so aim to drive the flagged share down and the burstiness up, not to
literally zero.

## 5. The humanization rulebook (what actually moved the score)

Apply to **flagged prose only**. Keep the register academic but let a real person
show through. Ordered by impact:

### 5.1 Kill the colon "statement: elaboration" habit  ⟵ highest impact
AI loves `Claim: supporting detail`. It's the single strongest tell in polished
academic text. Target **≤ 3–4 colons in the entire body**.
- Before: `El hallazgo apunta al canal: hay herramientas que superan el 97 %...`
- After: `El hallazgo no apunta tanto a la tecnología. Apunta al canal. Ya hay
  herramientas que superan el 97 %...`

### 5.2 Break symmetric enumerations
`dos cosas:`, `tres frentes:`, `cuatro ejes:`, `el patrón es doble:`,
`not only… but also…`. Any "here are N balanced items" scaffolding reads as
machine-planned. Dissolve into running prose or separate short sentences of
*uneven* length. Never keep three parallel clauses in a row.

### 5.3 Maximize burstiness (sentence-length variance)
Humans write a 3-word sentence next to a 40-word one. AI clusters near the mean.
- Mix fragments (`Ya se probó.` `Información, no trámite.`) with long winding
  sentences.
- Targets that correlate with passing (measured): **mean sentence length
  ~13–15 words**, and lots of very short sentences pulling the distribution wide.
- Insert genuine questions where natural (`¿Sabe el vecino a qué hora pasa?`).

### 5.4 First person + stance
Where the text reports the authors' own work, use `we/nosotros`:
`aplicamos`, `pusimos en diálogo`, `lo que encontramos`, `we asked`,
`we put X next to Y`. Neutral third-person exposition is an AI signature.

### 5.5 Concrete, slightly messy detail
Replace abstract summaries with specific, imperfect images.
- Before: `residuos amontonados en la vereda` (tidy)
- After: `Una funda que los perros abrieron de madrugada. Bolsas amontonadas
  esperando un camión que ya se fue.`

### 5.6 Vary paragraph openings
Don't start every paragraph with a topic sentence. Open with a question, a
fragment, a datum, an aside. Break the essay-template cadence.

### 5.7 Register-appropriate colloquialism (ES)
`la plata`, `a los tumbos`, `le ponga el hombro`, `da la talla`, `sin
maquillaje`. Enough to sound human; not so much it breaks academic tone.

### 5.8 Full "Signs of AI writing" checklist (baked in — see §11)
This skill folds in the complete Wikipedia "Signs of AI writing" guidance (ES and
EN). Remove/repair every one of these:
- Inflated significance / legacy talk (`marca un hito`, `desempeña un papel
  crucial`, `testament to`, `pivotal moment`).
- Promotional/peacock language (`vibrante`, `rico en`, `robust`, `seamless`,
  `must-visit`).
- Superficial `-ing`/`-ando` participle tails that fake depth.
- Vague attribution (`los expertos creen`, `studies show`, `observers note`).
- "Challenges and future prospects" filler sections.
- AI vocab clusters (`además`, `crucial`, `panorama`, `subrayar`, `fomentar`,
  `furthermore`, `delve`, `leverage`, `underscore`, `landscape`, `tapestry`).
- Copula avoidance (`sirve como`/`serves as` → `es`/`is`).
- Negative parallelism (`no solo… sino`, `not only… but also`).
- Rule of three (force groups of two or four, or dissolve).
- Forced synonym carousel; false-range "de X a Y / from X to Y".
- Em-dash overuse (`—`) → commas/parentheses.
- Bold overuse, inline-header bullet lists, Title Case headers, emojis, curly
  quotes.
- Collaboration/chatbot artifacts (`¡claro!`, `hope this helps`), knowledge-
  cutoff disclaimers, sycophantic tone, filler phrases, over-hedging, generic
  upbeat conclusions.

### 5.9 What you must NOT change
Citations `(Autor, año)`, numbers, %, dates, times (`07h00`), proper nouns,
the reference list, headings text, and the paragraph/section structure.

---

## 6. Rebuild the .docx (surgical, format-preserving)

Edit `word/document.xml` in place — never regenerate the doc (you'd lose styles,
hanging indents, hyperlinks). For each target paragraph, collapse its runs and
drop the new text into the first run so formatting is kept.

`scripts/replace_paragraphs.py` takes a JSON map `{paragraph_index: "new text"}`
and does exactly this (handles multi-run paragraphs, XML-escapes, forces
`xml:space="preserve"`, validates well-formedness).

```bash
python3 scripts/replace_paragraphs.py unpacked/ edits.json
(cd unpacked && rm -f ../out.docx && zip -Xrq ../out.docx .)
# optional validation if the Anthropic docx skill is present:
python3 <docx-skill>/scripts/office/validate.py out.docx --original input.docx
```

Sanity check after every rebuild: **paragraph count unchanged** (e.g. 51 → 51)
and the XML parses.

---

## 7. Measure before delivering

Run `scripts/text_metrics.py unpacked/ <body_indices>`:

| Metric | AI-ish | Human target |
|---|---|---|
| Colons in body | 20+ | **≤ 4** |
| Mean sentence length | 20–25 words | **13–16** |
| Sentence-length stdev | low vs mean | as high as reads naturally |
| Em-dashes | several | ~0 |
| Sentence count (same text) | fewer/longer | more/shorter |

Real trajectory that reached 13%: colons **24 → 12 → 3**, mean length
**22.4 → 14.6 → 13.8 words**.

---

## 8. Iterate (this is why it works)

You usually can't run the institutional detector yourself (Compilatio runs inside
the user's LMS/Canvas). So:

1. Deliver a version, ask the user to submit it and return the new report PDF.
2. Re-run §4 on the new report — the blue set shrinks each round.
3. Rewrite **only the still-blue paragraphs**, harder (more §5.1/§5.2/§5.3).
4. Leave now-clean paragraphs frozen.
5. Repeat until the score is at target.

Version the files (`_v5`, `_v6`, …) so the user can compare and roll back.

Be honest about limits: the score is statistical, not guaranteed; you cannot
promise an exact number; and you do not run the institutional tool — the user does.

---

## 8b. Knowledge baked into this skill

This skill is a consolidation of everything used to take the reference article
from 50% to 13%. It does not depend on other skills being installed — the
relevant knowledge is embedded here:

- **Wikipedia "Signs of AI writing"** (via the `humanizer` / `humanizer-es` /
  `humanize-writing` guides) — the full content/linguistic/style pattern
  catalogue, condensed in §5.8 and enforced by `scan_leaks.py`.
- **Stylometric-detector findings** from the real Compilatio Magister+ loop —
  the report-color parsing (§4), and the empirical result that colon-lists and
  symmetric enumerations are the highest-value fixes (§5.1–5.2, §7 targets).
- **Burstiness metrics** (`text_metrics.py`) and a heuristic **leak scanner**
  (`scan_leaks.py`) for blind mode.
- **docx surgery** (from the `docx` skill approach) — in-place XML edits that
  preserve styles instead of regenerating the document (§6).
- **Optional detector-API self-check** (§9) if a key is available.

If any of those standalone skills *are* installed, they compose fine, but none
are required.

## 9. Optional: self-check with an AI detector API

If a detector API key is configured (e.g. `HUMANIZERAI_API_KEY` for the
`detect-ai` skill), score the humanized text before the user submits, to catch
obvious regressions. Absent a key, rely on §7 metrics + the user's report loop.

---

## 10. Quick start

Common setup:
```
pip install pymupdf pypdf defusedxml
unzip the .docx → note body paragraph indices (§3)
```

**A) Report-driven (recommended when a report exists):**
```
1. python3 scripts/analyze_report.py report.pdf         # blue (IA) + green (similarity)
2. map blue passages → paragraph indices; rewrite per §5 into edits.json
3. python3 scripts/replace_paragraphs.py unpacked/ edits.json ; zip → out.docx
4. python3 scripts/text_metrics.py unpacked/ <indices>  # confirm §7 targets
5. hand back out.docx (_vN); get next report; iterate §8 on remaining blue
```

**B) Blind (no report):**
```
1. python3 scripts/scan_leaks.py unpacked/ <indices>    # rank likely AI tells
2. rewrite the top offenders per §5 into edits.json
3. python3 scripts/replace_paragraphs.py unpacked/ edits.json ; zip → out.docx
4. python3 scripts/text_metrics.py unpacked/ <indices>  # confirm §7 targets
5. re-run scan_leaks; repeat until flagged share is low and metrics are human
```

Files in this skill:
```
SKILL.md
scripts/analyze_report.py       # report-driven: blue(IA)/green(similarity) from PDF
scripts/scan_leaks.py           # blind: heuristic AI-leak scanner (ES+EN)
scripts/replace_paragraphs.py   # rewrite paragraphs in .docx, keep formatting
scripts/text_metrics.py         # burstiness metrics
```

Deliver the file, a short changelog of which paragraphs changed and why, the
metric deltas, and the honest note from §8.