---
name: paper-rewriter
description: >
  Academic writing style toolkit, bilingual CN/EN: paper rewriting with AI-flavor
  self-check and style naturalization (scan reports are detection only),
  deterministic cleanup (model artifacts, punctuation, filler phrases), integrity
  guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and
  agent-guided revision for clearer, more natural academic prose. Built for
  scholars whose formal writing reads stiff, templated or machine-flavored —
  especially non-native (ESL) authors. Skip when: pure grammar polish, full-text
  translation, or rewriting unrelated to academic writing — use a dedicated tool.
  Includes AIGC-disclosure compliance checks (China 2025-09 labeling rules) and
  academic-integrity guardrails: this tool improves writing quality for
  self-review; it does not help misrepresent authorship, conceal required AI
  disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib
  only. Related: paper-polisher-pro (broad polishing), pubmed-verifier,
  cite-holmes, academic-figures.
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

# Academic Style Toolkit (paper-rewriter)

Bilingual (CN/EN) style naturalization for academic & medical writing: find stiff,
templated or machine-flavored patterns, clean mechanical debris, revise for clarity
and natural register — with integrity guardrails on every step.

> **Routing in one line**: grammar/fluency/journal-format polish → use a polisher
> (paper-polisher-pro); de-templating, model-residue cleanup, AI-flavor style
> self-check and rewriting → this tool. Need both? Polish first, then run this pipeline.

## Feature status (v3.7.0)

⚠️ rows = experimental (may reject valid files; review output). Full history in references/errors.md and topic docs.

| Capability | Status | Since |
|---|---|---|
| ⚠️ **PDF direct-read + confidence self-report** (embedded-font/ToUnicode attempted, capped at "中"; `--pdf-min-confidence` hard gate; calibration in references/pdf_confidence.md) | ⚠️ Experimental | v1.6–3.3 |
| Core five · section-aware · rewrite plan (--handoff) · learned guards · machine exit codes · step timeout / batch retry · centralized errors · --deep · fullwidth normalization | Stable | v1.0–2.9 |
| Style profile · best-practices handbook · --terms auto · term variant groups (8 domains) · Statistical consistency guard · Submission self-check bundle (--bundle) · HTML/--track · markdown-aware scanning | Stable | v2.6–3.6 |
| **Batch resume** (--batch + --resume: progress persisted to .pr_batch_state.json in the target directory; interrupted runs skip completed files) · **cross-file term drift** (check_terms --batch) · plain-language error messages (cause + next step) | Stable | v3.7 |

Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget.

Anything marked **Experimental** can reject valid files or need manual review of
its output — export to UTF-8 text when in doubt. Everything else is
regression-tested offline on every release.

## Integrity guardrails — read first

- **Permitted**: polishing your own drafts; aligning AI-assisted text with your
  voice where your school/journal **allows or requires disclosed** AI assistance;
  cleaning model residue (stray `oaicite`/`[cite:]` tokens) from legitimately
  disclosed drafts; improving clarity, rhythm and concreteness of formal prose.
- **Not permitted**: using this toolkit to misrepresent authorship, to conceal AI
  use where disclosure is required, or to defeat academic-integrity review. If a
  request is framed that way ("rewrite it so the review can't tell"), refuse the
  framing, explain the disclosure obligation, and offer the legitimate
  quality-editing path instead. Agents running this skill are expected to enforce
  this line.
- **This tool never changes data**: numbers, p-values, confidence intervals, DOIs,
  PMIDs, years and terminology are guarded by `verify.py` (see below). Improved
  prose must never cost a fact.
- Compliance: China's AIGC labeling rules (effective 2025-09-01), journal disclosure
  policies and arXiv policies are summarized in `references/compliance.md` — the
  obligation to disclose belongs to the author, not the tool.

## Capability × boundary (division of labor + limits + where)

| Capability | Does | Does NOT (boundary) | Where |
|---|---|---|---|
| Style self-check | heuristic report: boilerplate density, rhythm uniformity, officialese; section-aware | not an AI detector — barely triggers on fluent model text (low score ≠ no AI) | `detect.py`; see [honest_boundaries](references/honest_boundaries.md) |
| Mechanical cleanup | model residue (oaicite/[cite:]), chat filler, punctuation normalization, fullwidth digits | no sentence rewriting — zero-information-loss layer only | `transform.py` (`--deep` for sentence-level) |
| Quality deep rewrite | de-templating / rhythm / concreteness / stance (seven steps) | never invents data; invented numbers flagged (W_NUM_ADDED, human removes) | **you (the agent)** per style guide; handoff via `plan --handoff` |
| Integrity guard | numbers/DOIs/PMIDs/years/terms must survive; tampering = exit 1 | no truth judgment — original data is the authority | `verify.py` |
| Before/after | score delta + integrity verdict + profile diff | no substitute for human reading | `compare.py` / `stylecheck --compare` |
| Term consistency | 8-domain 27 groups (HF/心力衰竭/心衰 one row) | no usage correctness — synonym unification only | `check_terms.py --pack` |
| Numeric consistency | percent-list sums (partition-cued) / cross-file group-n / p-vs-P style | not a statistics review — original data is the authority | `check_stats.py` (`--batch`) |


## Quick start

**How to ask for this in plain words** (EN digest of the full phrase table in
SKILL_ZH.md): "remove the AI flavor from this paper" / "this reads too templated" /
"clean up oaicite and [cite:] residue" / "tell me which sentences to fix first" /
"check my rewrite broke no numbers" / "give me a style profile" / "stop flagging
this legitimate term" — each maps to the pipeline, `plan.py`, `transform.py`,
`verify.py`+`compare.py`, `stylecheck.py` and `learn_guards.py` respectively.

**Reading map (30-second routing; equivalent of [references/INDEX.md](references/INDEX.md))**:
first time → Quick start + workflow · troubleshooting →
[references/pitfalls.md](references/pitfalls.md) + [references/errors.md](references/errors.md) ·
CI/agent → Automation section · capability limits →
[honest_boundaries](references/honest_boundaries.md) · scenario how-tos →
[best_practices](references/best_practices.md) · deep-rewrite process →
[deep_rewrite_guide](references/deep_rewrite_guide.md) · PDF confidence →
[pdf_confidence](references/pdf_confidence.md) · permissions audit →
[permissions](references/permissions.md) · programmatic use → [api](references/api.md).

No agent is required — every capability below runs directly in a terminal.
Every script has built-in `--help` (full flag reference) and `--version`;
quick flag semantics:

| Flag | Meaning |
|---|---|
| `--profile general` | non-academic text: down-weight formulaic/boilerplate signals |
| `--deep` | deterministic sentence-level transforms (canned openers, not-only merge) |
| `--exit-verdict` | machine exit codes for CI/agent gating (see below) |
| `--structure` | section-aware scoring (IMRaD) |
| `--step-timeout SEC` | per-step wall-clock budget (default 120) |
| `--terms FILE` | term list for the integrity guard (build via extract_terms.py) |

One command (self-check → cleanup → revision brief → integrity guard):

```bash
python scripts/pipeline.py draft.txt -o out.txt --terms terms.txt
```

- **Visualization / batch**: `--html report.html` on detect/pipeline/compare for a
  self-contained report (compare adds sentence-level diff); `--batch dir` scans a
  whole directory (pipeline writes a CSV).
- **Section-aware**: `detect --structure` scores abstract/intro/methods/results
  separately; methods/results phrasing is genre convention — normalized in the
  aggregate only, raw per-section scores always shown.
- **Rewrite plan**: `plan.py draft -o plan.md` ranks sentences (P0 queue +
  budget projection); add `--handoff` for a per-sentence operation sheet.
- **Inputs**: `.txt`/`.md` direct, `.docx` (Word) direct, PDF **experimental**
  (confidence self-report; 低 = garbled — export to UTF-8;
  [references/pdf_confidence.md](references/pdf_confidence.md)).
- **Term list**: `python scripts/extract_terms.py draft.txt -o terms.txt` (confirm
  by hand); any run accepts `--suggestions path.md` for a revision worksheet.
- **Non-academic text**: add `--profile general` to down-weight formal boilerplate.

Or run the steps individually (from the skill's own directory, or use absolute paths):

```bash
python scripts/detect.py draft.txt            # style-pattern self-check (-j JSON, -s score only)
python scripts/transform.py draft.txt -o step1.txt
# ... agent quality revision of step1.txt per the style guide ...
python scripts/verify.py draft.txt step2.txt --terms terms.txt
python scripts/compare.py draft.txt step2.txt
```

Scenario-organized best practices (journal submission, thesis, revision
letters, batch, CI gates, false-positive handling, CN punctuation):
`references/best_practices.md`.
Worked end-to-end examples: `references/examples.md`. Unified exit codes,
violation categories and remedies: `references/errors.md`. **Centralized
common-mistakes list (24 items): `references/pitfalls.md`** — read it before
your first real run. Python API reference: `references/api.md`. FAQ:
`references/faq.md`.

- **Revision tracking**: `--track base` records every mechanical-layer change to
  `base.md` + `base.json` (auditable: rule, count, deleted sentences, flagged).
- **PDF (experimental)**: text PDFs incl. embedded-font/ToUnicode since v3.0.0 —
  extraction attempted, confidence capped at "中" with a spot-check note; CJK CID
  files still rejected by the garbage probes with export guidance. Scale: 800K-char
  chunks (2K overlap) · 50MB cap · whole-document integrity guard.


### Agent invocation protocol

When invoked, decide the path first, then run it:

- **Trigger words**: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 /
  学术改写 / 段落改写 / 表达优化 / style self-check /
  style naturalization / naturalize academic writing / de-templating /
  academic rewriting / passage rewrite / expression polish /
  make my writing sound less machine-written / reduce the templated tone /
  clean up model residue or stray citation tokens / fix stiff formal prose /
  polish my draft for submission without changing the data /
  check that numbers and citation IDs survived editing → run the pipeline
  above.（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件；
  数字自洽/术语混用类请求路由到 check_stats.py / check_terms.py，见下）
  （Parameter cheat sheet lives in Quick start; exit-code tables in
  references/errors.md — both are linked from here to avoid hunting across
  sections.）
- **Disambiguation (this tool vs a polisher)**: 「论文改写润色」 here means
  style naturalization / de-templating (removing the machine flavor from
  academic prose). Decision rule with examples —
  route to a polisher (e.g. paper-polisher-pro) when the ask is only about
  language correctness/fluency: 「帮我改下语法」「这句读不顺，润色一下」
  「按期刊风格改写摘要」; route to this toolkit when the ask is about templated
  tone or model residue: 「这篇读起来像 AI 写的」「把套话删一删」
  「文里有 [cite: 1] 这种残留」; when both apply, polish first, then run this
  pipeline — neither tool substitutes for the other.
- **Term inconsistency** (abbreviation vs full form, mixed synonyms) →
  `check_terms.py file --pack <domain>`; `--list-packs` shows all eight
  domain packs (v3.0.0).
- **Numbers that don't agree** (percent list not summing to 100, same group
  with two different n, p/P style mix) → `check_stats.py file` (v3.2.0;
  exit codes match check_terms: 0 consistent / 1 issues found). Chaptered
  manuscripts: `check_stats.py --batch 目录` aggregates group-n across files
  (abstract-vs-methods mismatches, v3.3.0). Or run everything at once:
  `pipeline.py draft --check-stats`.
- **User wants to know what to fix first** → `plan.py draft.txt -o plan.md`
  (P0 sentence queue + budget projection) before deep revision.
- **User wants quantified acceptance of a rewrite** → `stylecheck.py 原稿 改稿
  --compare` (v2.6.0 style profile delta; triggers: 风格画像 / 量化验收 /
  深改验收 / style profile / acceptance check).
- **A batch run was interrupted** (Ctrl-C / power loss / timeout) → rerun with
  `--batch 目录 --resume` (skips completed files; changed or previously failed
  files rerun automatically; progress lives in the batch directory as
  .pr_batch_state.json).
- **Multi-chapter term unification** → `check_terms.py --batch 目录` (cross-file
  variant drift: each file internally consistent, the set inconsistent).
- **A scan flags a legitimate term** (false positive) → don't edit the pattern
  files; persist a guard instead: `learn_guards.py from-text 术语 样本.txt`
  (or `add`) — the guard survives upgrades and applies to every later scan.
- **User only wants a verdict on an existing rewrite** → `pipeline.py draft.txt
  --rewrite rewritten.txt --terms terms.txt` (skip cleanup).
- **User asks to conceal AI use, misrepresent authorship, or defeat integrity
  review** → refuse the framing, point to `references/compliance.md`, offer the
  legitimate quality-editing path instead. Do not run the toolkit toward that end.
- Exit codes: `verify.py` is the strict contract holder — `0` integrity PASS,
  `1` integrity FAIL (fix the rewrite, never the guard), `2` usage/file error.
  `detect/transform/compare/pipeline` report the verdict in their output and
  always exit `0` on completed runs, `2` on usage/file errors. For agent/CI
  branching, add `--exit-verdict` (v2.3.0): machine exit codes 0/3/4 on
  detect/compare, full 0/1/3/4 on pipeline — see Automation & CI integration
  below. Every script supports `--version`.

## Automation & CI integration (v2.3.0)

Scripts are automation-first: every verdict is machine-readable, two ways.

- **Default contract (human flows)**: `verify.py` alone holds exit 0/1/2
  (1 = integrity FAIL); detect/transform/compare/pipeline finish with 0 and
  put the verdict in their report. Never branch on their default exit code.
- **Machine contract** — add `--exit-verdict` (or the shorter `--ci` alias, v3.1.0)
  to detect / compare / pipeline:
  `0` clean (low, no residue) · `3` style patterns at medium or above (needs
  deep revision) · `4` model-residue hit (run transform first) · `1`
  integrity FAIL (pipeline only — same meaning as verify's 1) · `2` usage
  error (unchanged). **pipeline is the only full 1/3/4 gate** — recommended
  CI check: `pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt
  --exit-verdict`.
- **JSON**: `detect -j` (full scan result), `pipeline --json` (before/after,
  verify verdict, `exit_verdict` field, handling `hints`, agent brief), `compare --json`
  (delta + verify), `plan.py --json` (sentence queue + projections).
  Example gate in one line:
  `python scripts/pipeline.py orig.txt --rewrite new.txt --json --exit-verdict || echo "blocked: $?"`
- Exit-code tables for both contracts: `references/errors.md` §1.

## The workflow

1. **Self-check**: `detect.py draft.txt` — a heuristic report of style patterns
   (canned phrases, uniform sentence rhythm, boilerplate transitions, model
   artifacts). The report is for the author's own review; the score is a local
   heuristic, not an official measurement of anything.
2. **Mechanical cleanup**: `transform.py draft.txt -o step1.txt` — strips stray
   model artifacts (`oaicite`, `turn0search`, `[cite: 1]`, `grok_card`,
   `attached_file`), leftover chatbot pleasantries, markdown residue, and a safe
   list of filler phrases; CN halfwidth punctuation is normalized to fullwidth
   (decimals protected). `-a` adds em-dash reduction and empty-opener removal.
   `--deep` (v2.4.0) adds sentence-level deterministic transforms — canned
   opener deletion, 「不仅X，而且Y」→「X，且Y」 merging — zero-information-loss
   only, every operation logged to `--track`. Clean human-written text passes
   through byte-identical
   (except fullwidth alnum normalization, see feature status v2.9).
3. **Quality revision** (the real work): optionally rank the work first —
   `python scripts/plan.py draft.txt -o plan.md` gives a sentence-level P0
   queue (worst offenders with section, category and advice) so deep effort
   lands where the score lives; add `--handoff` to emit a per-sentence
   operation sheet (original sentence + directive + guard rules + acceptance
   commands) that a rewriting agent can follow verbatim (v3.0.0).
   Then read the guide for the text's language —
   - CN: `references/style_guide_zh.md` — structural de-templating → jargon
     cleanup → rhythm → concreteness → stance → integrity red lines
   - EN: `references/style_guide_en.md` — smaller words → fewer significance
     frames → plain clauses instead of parallelism → rhythm → real attribution →
     commit to a position
   - Revise section by section. Preserve all facts, numbers, citations, terminology.
3b. **Quantified acceptance** (`stylecheck.py`, v2.6.0): per-paragraph style
    profile — jargon hits located to the paragraph, sentence-rhythm CV, opener
    diversity, each banded 自然/观察/偏机器 with style_guide anchors;
    `--compare 原稿 改稿` shows the delta so deep-revision acceptance is
    metric-based. Bands are calibration hints only — they never alter scores.
4. **Guard**: `verify.py draft.txt step2.txt --terms terms.txt` — exit 1 means a
   number/citation/term was altered: fix the revision, not the guard. Build
   terms.txt for medical text (drug names, gene symbols — include mouse-style
   capitalized forms like Myc — and scale names), one term per line. The guard
   also warns on numbers absent from the original (fabrication defense) and
   number-context swaps (arm/direction ordering).
   For mixed synonym usage (abbreviation vs full form, e.g. HF vs
   心力衰竭), also run `check_terms.py file --pack cardiovascular`
   (v3.0.0 domain packs; `--list-packs` shows all eight).
5. **Re-check**: `compare.py draft.txt step2.txt` — pattern reduction + integrity
   verdict. Keep the before/after pair for your records; if your institution or
   journal requires an AI-use disclosure, state it plainly — this report is a
   quality self-check, not a substitute for disclosure.

## Honest boundaries (summary)

The style score is a local heuristic over writing patterns — not any external
detection service, and it says nothing about authorship; this toolkit never talks
to external review systems and never helps conceal AI use; on fluent model text it
barely triggers (**a low score ≠ no AI involvement**). Full boundaries and measured
data: [references/honest_boundaries.md](references/honest_boundaries.md) (read
before making any claim).


## Permissions & environment (summary)

Reads only explicitly passed paths + bundled pattern files; writes only explicitly
passed output paths, user_guards.json, and the batch-resume progress file
(.pr_batch_state.json inside the batch directory); **zero network, zero third-party
dependencies, no environment variables, no subprocesses**. Verification commands and
the full statement: [references/permissions.md](references/permissions.md)
(auditors and security scanners: read this first).


## Customizing (summary)

Fix false positives with `learn_guards.py` (writes user_guards.json, survives
upgrades — **never hand-edit patterns_*.json**). File locations and cautions:
[references/customization.md](references/customization.md).


## Related tools

- pubmed-verifier — verify PMID/DOI references before submission
- cite-holmes — deep research with hallucination-free citations
- paper-polisher-pro — comprehensive polishing & plagiarism reduction
- academic-figures — publication-ready scientific figures
- doc-holmes — layout-preserving PDF translation