# Humanize Paper
[English](README.md) | [简体中文](README.zh-CN.md)
`humanize-paper` is a Codex skill for revising academic writing in English and Chinese. You can give it a paragraph that sounds canned, a section full of internal experiment names, or a complete manuscript whose argument has become buried under implementation detail. It chooses the scope from the material you provide.
For a paragraph or section, the skill stays local. It looks for repeated sentence frames, stock transitions, empty emphasis, defensive qualifications, terminology drift, and prose that sounds unlike the research community it is written for. It also handles Chinese patterns that are easy to miss with an English checklist: repeated 否定—对照 constructions, balanced lists, filler abstractions, and habitual use of `——`.
For a complete manuscript, it can work at a different level. It checks whether the motivation arrives before the solution, whether each design choice answers a stated requirement, whether controls sit next to the explanations they test, and whether results are ordered by their role in the argument rather than by the date they were run. It may move or compress material when those problems are present. If the structure already works, it leaves it alone.
In both cases, the default rule is the same: revision must not change what the paper knows. Facts, negation, modality, scope, comparison direction, aggregation, numbers, formulas, citations, dataset names, model names, and technical terms are locked. For example, `may improve` cannot become `improves`, and `within 0.5 points` cannot become `matches` simply because the latter sounds cleaner.
## Things it catches
The language pass covers familiar AI-writing patterns, but does not treat a word list as a detector. A single `Moreover` or em dash is not a finding. Repetition, empty function, and mismatch with the surrounding evidence are what matter.
Examples include:
- stock language such as `delve`, `pivotal`, `it is worth noting`, and `plays a crucial role`;
- paragraphs that repeatedly follow the same problem–method–benefit–summary mold;
- automatic openings and endings such as “another key challenge” and “taken together”;
- empty `not merely ... but ...` contrasts, decorative metaphors, and promotional adjectives;
- unnecessary self-defence, including “we do not claim” or “our goal is merely” when no real scope boundary is being stated;
- stacked hedges around a direct result;
- internal names such as `run_v3_final`, `config_A2`, checkpoint names, W&B or Slurm IDs, hostnames, and absolute paths;
- implementation history presented as scientific organization;
- generic limitation apologies that never say which claim is bounded, where, or why.
Internal names are not replaced by guesswork. If the available files do not establish what `config_A2` and `config_A3` mean, the skill leaves the identity unresolved for the author instead of merging or renaming them.
## Three kinds of input
**Excerpt.** A paragraph or section gets a local, meaning-preserving edit. The skill does not infer a manuscript thesis or rearrange distant sections from partial context.
**Manuscript.** A substantially complete paper permits argument reconstruction. The skill first diagnoses the current structure; cross-section edits are made only for a named problem.
**Manuscript with evidence.** Tables, theorem statements, result summaries, or raw records can authorize evidence-bounded claim calibration. Without that independent evidence, claim strength remains locked even when the wording appears too cautious.
## Boundaries
This skill is not an AI detector and does not produce an AI probability. It is also not intended to evade a detector. It will not insert mistakes, fabricate citations or experiments, invent personal experience, or make unsupported claims sound more confident.
## Install
```bash
git clone https://github.com/SyntaxSmith/humanize-paper.git ~/.codex/humanize-paper
mkdir -p ~/.codex/skills
ln -s ~/.codex/humanize-paper/humanize-paper ~/.codex/skills/humanize-paper
```
If you clone the repository elsewhere, link its `humanize-paper` directory into `~/.codex/skills/`.
## Use
For a complete manuscript:
```text
Use $humanize-paper to reconstruct and revise this manuscript. Preserve its claims and evidence, and report any unresolved claim–evidence mismatch.
```
For a local rewrite:
```text
Use $humanize-paper to revise this section without changing its claims, scope, modality, citations, numbers, or terminology.
```
For diagnosis only:
```text
Use $humanize-paper to diagnose the manuscript. Separate structural problems from language-level patterns, and do not rewrite it yet.
```
Codex can also select the skill automatically for academic-writing requests such as “humanize paper,” “rebuild the narrative,” “improve the logic,” “去 AI 味,” or “润色成人写的.”
## Included tools
- [`SKILL.md`](humanize-paper/SKILL.md): workflow, permissions, stop conditions, and output contract.
- [`signal-catalog.md`](humanize-paper/references/signal-catalog.md): examples of structural and language-level problems.
- [`community-lexicon.md`](humanize-paper/references/community-lexicon.md): community terminology, internal artifact names, and Chinese writing patterns.
- [`manuscript-reconstruction.md`](humanize-paper/references/manuscript-reconstruction.md): the full-manuscript route.
- [`diagnose.py`](humanize-paper/scripts/diagnose.py): a standard-library script that locates candidates without assigning an AI score.
- [`verify_invariants.py`](humanize-paper/scripts/verify_invariants.py): a check for protected spans and changes in semantic-risk markers.
Run the tests with:
```bash
python3 -m unittest discover -s humanize-paper/scripts -p 'test_*.py'
```
The invariant checker catches some concrete mistakes, but it cannot prove that two passages mean the same thing. Terminology, named entities, citation scope, and discourse relations still need to be read in context.
## License
[MIT](LICENSE)