humanize

What does humanize do?

Revise the prose of a LaTeX paper so it is easier to read and sounds like a careful human author, and deliver the result as a separate copy of the .tex file.

The point is not to "disguise" anything. AI-assisted drafts tend to share a recognisable texture — over-signposted, inflated, rhythmically uniform, padded with phrases that carry no information. Reviewers notice it and it makes papers harder to read. A good human editor removes that texture by making each sentence say something specific in the plainest form that still fits the register of an academic paper.

What you must not change

A paper is a record of claims. A readability edit that changes a claim is a bug, not a style choice. So:

• Leave the preamble untouched (everything before \begin{document}).
• Never edit math: inline $…$, \(…\), display math, and math environments (equation, align, …) stay byte-for-byte identical.
• Keep every \cite…, \ref/\eqref/\cref, \label, \includegraphics, \input and environment boundary. You may move a citation within a sentence you restructure, but the same keys must still support the same statement.
• Keep every number in the prose (statistics, p-values, sample sizes, ranges) and its attachment to the right quantity.
• Keep the strength of claims. Do not turn "suggests" into "shows" or "did not differ consistently" into "were equivalent". Calibrated hedging is part of the science; only remove hedges that are stacked or empty ("may potentially", "it could be argued that perhaps").
• Keep the author's terms of art. If the paper defines "operational regimes", "safety zone", "MRP", use exactly those. Do not swap technical words for synonyms — "robust", "significant", "novel" are fine when they are technical, they only become AI tics when used as decoration.
• Keep the language and spelling variant (British "behaviour/penalises" stays British; Portuguese stays Portuguese).
• Don't touch table contents, % comments, \todo{} markers, or the bibliography.

If a sentence is unclear in a way that you can only fix by guessing what the authors meant, leave it and list it in your report instead of rewriting it.

Workflow

1. Identify the target

Take the file from the user's message or slash-command argument. If none is given, infer it from the conversation (the paper being worked on, or the editor's active file — get_editor_state if the GilzaCode tools are available); if several .tex files are candidates (e.g., main6.tex and main7.tex), pick the most recent draft and say which you picked. If the user asked for specific sections only, revise only those.

If the main file pulls content in with \input/\include, humanize each included prose file into its own <name>_humanized.tex and point the main copy's \input lines at them.

2. Make the copy

Copy the file to <stem>_humanized.tex in the same directory (so figures, .bib, and class files still resolve). If that file already exists, ask before overwriting, or use <stem>_humanized2.tex if you cannot ask. All edits go to the copy. Never write to the original.

3. Get a map of the problems

Run the scanner on the original to see where AI-style patterns cluster:

python <skill-dir>/scripts/ai_scan.py path/to/paper.tex

It reports flagged phrases with line numbers, em-dash density, and sentence-length statistics per section. Treat it as a heat map, not a to-do list: a hit is a place to look, and many hits are fine in context. Removing every flagged word while leaving the sentence structure intact produces text that is just as mechanical. Read references/patterns.md for the full catalogue of patterns (English and Portuguese) and for how to fix each kind — read it before you start editing.

4. Revise, section by section

Read one section (or a few paragraphs) at a time and edit the copy with targeted Edit calls on prose. Working paragraph by paragraph keeps the LaTeX intact and lets you hold the argument of the section in mind.

For each paragraph ask: what is this paragraph claiming, and what is the shortest clear way a competent author in this field would say it? Then:

• Cut what carries no information: meta-commentary ("It is worth noting that", "In this section, we will discuss"), restating summaries at the end of paragraphs, throat-clearing openers, decorative intensifiers.
• Prefer the concrete: replace a vague abstraction with the specific thing ("improves performance" → "survives 48 steps longer", if the paper says so somewhere nearby; otherwise just keep it plain).
• Fix sentence structure for readability: put subject and verb close together and near the start; split sentences that carry three ideas; join choppy fragments that belong together; move familiar information to the start of a sentence and new information to the end; turn nominalisations back into verbs ("perform an analysis of" → "analyse").
• Vary the rhythm the way a person does — some short sentences, some long — instead of a uniform cadence or uniform paragraph shapes.
• Break formulaic structures: forced triads, "not only X but also Y", "X, not Y" contrasts used for effect, colon reveals ("The answer is simple: …"), chains of em-dashes, and paragraphs that all open with a transition word.
• Keep what already works. Many sentences in a decent draft are fine. Touching every sentence is itself an AI signature and raises the risk of changing meaning. A typical good pass rewrites somewhere between a fifth and a half of the sentences, concentrated where the scanner and your reading find problems.

Section titles, captions and the abstract are prose and can be edited with the same care; keep titles short and keep caption content (what is plotted, what the symbols mean) complete.

5. Verify integrity

Run the checker comparing original and copy:

python <skill-dir>/scripts/check_integrity.py path/to/paper.tex path/to/paper_humanized.tex

It compares the preamble, math segments, citation keys, refs, labels, environments, graphics paths, brace balance, and numbers in prose. Fix every ERROR before finishing. Look at each WARN (usually a number or citation that moved or disappeared) and either restore it or confirm the change is harmless. Then re-run ai_scan.py on the copy to confirm the hot spots cooled down.

If a LaTeX compiler is available (GilzaCode's compile_latex, tectonic, latexmk, pdflatex), compile the copy to make sure it builds. Don't spend long on this if the environment has no compiler — the integrity check already covers the usual breakage.

6. Report

Finish with a short report in the conversation, in the user's language:

• Path of the humanized copy (the original is unchanged).
• What kinds of changes you made, with 3–5 representative before/after pairs (one line each, trimmed).
• Scanner numbers before vs after (flagged phrases, em-dashes, mean sentence length) — briefly.
• Integrity-check result.
• Anything you deliberately left alone and why: passages that seem unclear or possibly wrong in substance, claims that look stronger than the evidence, inconsistent terminology. Flag these; don't fix them silently.

If the user is preparing a revision for a journal, offer to produce a latexdiff between the original and the copy (if latexdiff is installed) so they can review the changes visually.