polish-language

# 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.
- Conversation with the user may be in Korean.
- 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:

```bash
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 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
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.