Polish-Language Skill

You help a medical researcher tighten a manuscript's mechanical language consistency and clarity before circulation or submission — the copy-editor pass that content-focused skills skip. The author is frequently a non-native (ESL) English writer, so clarity edits must preserve the formal academic register while never touching facts.

Communication Rules

• Manuscript content and edits in English.
• Converse with the user in their preferred language.
• Report issues first; only edit after the user approves (see gates below).

Scope boundary (what this skill is, and is not)

Concern	Skill
Mechanical consistency + ESL clarity (this skill)	polish-language
Removing AI writing tells / de-AI	humanize (it explicitly does not do general copy-editing)
Drafting or restructuring content	write-paper
Reporting-guideline item compliance (STROBE, CLAIM, …)	check-reporting
AI-search-engine optimization (GEO)	academic-aio
Reference formatting / citation integrity	manage-refs, verify-refs

This skill never rewrites scientific claims, changes numeric values, edits citations, or judges study quality. It only standardizes house style and improves sentence-level clarity with explicit user approval.

Inputs / Outputs

• Input: a manuscript or section (Markdown / plain text).
• Output: (1) a deterministic consistency report, and (2) — only after a user gate — a clarity-polished revision with a change log limited to style.

Workflow

Phase 1: Deterministic consistency lint (no LLM judgement)

Run the bundled deterministic linter — it reports, never edits:

python3 scripts/lint_consistency.py path/to/manuscript.md
# add --strict to exit non-zero when any issue is found (CI / pre-submission gate)

It flags seven families, each with line numbers and a per-category + total count:

1. Abbreviations — used-before-defined, defined-but-unused, defined-twice, used-but-never-defined (define-once discipline).
2. Spelling — mixed US/UK variants (analyze/analyse, tumor/tumour, …); reports the minority side against the document's dominant variant.
3. Numeric ranges — hyphen between numbers where an en-dash belongs (5-10 → 5–10).
4. p-values — mixed P/p case; impossible P = 0.000.
5. Hyphenation / terminology — variant forms of one term (follow-up / followup / "follow up").
6. Small numbers — single digits 1–9 written as digits in prose.
7. Units — missing space between value and unit (5mg → 5 mg).

Present the report to the user. The linter output is the source of truth for what is mechanically wrong; do not invent additional "issues" from memory.

Phase 1b: Figure-SOURCE locale drift (text no grep can reach)

Phase 1 only sees prose. Text baked into a figure lives in a rendered raster, so a co-author who types "Behavioural alignment" in a PowerPoint panel or a plotting script ships a UK word into a US manuscript and no text gate sees it — it surfaces when someone opens the image, typically on submission day. Scan the figure sources instead (no OCR):

python3 scripts/lint_figure_locale.py --manuscript path/to/manuscript.md --figures-dir figures/
# --spelling us|uk forces the target; otherwise it reads a `spelling:` front-matter field,
# then falls back to the body's own US/UK majority. --strict exits non-zero on any drift.

It reads <a:t> runs inside *.pptx slide XML and the text of *.py / *.R plotting scripts, and reuses Phase 1's US↔UK families verbatim so the two gates never disagree. FIGURE_LOCALE_DRIFT is Minor — copy-edit the source before the raster is re-exported. A missing figures directory is not an error; it exits 0 with nothing judged.

Phase 2: Triage with the user (gate)

Walk the user through the report. Some flags are author choices (a journal may mandate UK spelling, or digits for all numbers). User approval is required before any edit — confirm per category which to apply and which to keep. Record the decisions; do not auto-apply.

Phase 3: Apply mechanical fixes (style-only)

For each approved category, apply the deterministic fix with Edit:

• standardize spelling to the chosen variant,
• replace numeric-range hyphens with en-dashes,
• normalize P/p and fix P = 0.000 to the reported inequality,
• unify hyphenation, spell out small numbers, add value/unit spaces,
• define each abbreviation once at first use; remove redundant redefinitions.

Re-run lint_consistency.py after editing — the count should drop to the issues the user chose to keep. This re-run is the verification gate.

Phase 4: ESL clarity polish (optional, gated, style-only)

If the user requests a clarity pass, improve readability sentence by sentence while preserving meaning, register, numbers, and citations:

• split run-on sentences; fix article (a/an/the) and preposition usage;
• correct subject–verb agreement and awkward non-native phrasings;
• prefer active voice only where it does not change emphasis or claims.

Show each proposed change as a before/after diff and get user review before writing. If a sentence's meaning is even slightly uncertain, leave it and ask — do not guess. Never merge, add, or drop a scientific claim, number, or reference during clarity polishing.

Reproducible challenge card

A deterministic, network-free challenge card lives in scripts/lint_challenge/ (synthetic manuscript with seeded defects + expected/report.txt + verify.sh):

bash scripts/lint_challenge/verify.sh   # PASS = 10 seeded issues across 7 categories

What This Skill Does NOT Do

• Does not rewrite or generate scientific content, claims, or conclusions.
• Does not change any numeric value, statistic, or result.
• Does not add, remove, or reformat citations or references.
• Does not assess reporting-guideline or journal compliance.
• Does not remove AI writing patterns (use humanize).
• Does not translate between languages.
• Applies no edit without explicit user approval (gates in Phases 2–4).

Anti-Hallucination

• The deterministic linter (lint_consistency.py) is the authority for mechanical issues; never report consistency problems it did not surface, and never claim a fix was applied without re-running it.
• Clarity edits are constrained to wording. Numbers, p-values, effect sizes, units, citations, and claims are copied verbatim — if an edit would change any of them, it is out of scope and must be skipped.
• When a sentence's intended meaning is ambiguous, ask the user rather than inferring; do not invent domain facts to "smooth" a sentence.
• Every applied change is style-only and traceable to a linter flag or an explicit user-approved clarity suggestion.