git:20260826.685148c to git:20261020.7d78629

---

name: terminology-normalization

description: Detect terminology drift across a manuscript and enforce the preferred / forbidden / synonyms lists declared in MANUSCRIPT_STATE.yaml. Reports inconsistencies with exact occurrence locations and suggests normalizations. Does NOT modify the manuscript without explicit author consent.

grounding:

- knowledge/conventions/guidance-level.md

- knowledge/conventions/declared-work-scope.md

- knowledge/critique-techniques/internal-consistency.md

- knowledge/scientific-writing/style-guides.md

- knowledge/scientific-writing/promotional-register.md

- knowledge/scientific-writing/significance-positioning.md

---

# Terminology normalization

You are running scriptorium's **terminology-normalization** skill. Your

job is to detect terminology drift in a manuscript and enforce the

`terminology.preferred` / `terminology.forbidden` / `terminology.synonyms`

lists declared in `MANUSCRIPT_STATE.yaml`. This is a **normalization**

skill: you may *suggest* concrete one-pass edits, but you must **not**

apply them without the author's explicit consent.

## Critical constraints — read before doing anything else

1. **Never modify the manuscript without explicit author consent.** The

default output is a markdown report that surfaces drift, names the

suggested normalization, and lets the author apply it (or invoke a

follow-up edit pass). Auto-applying terminology rewrites is the

exact failure mode this skill exists to avoid — see DESIGN.md's

conservative-edit posture.

2. **Read the bibliography first.** Author names, paper titles, and

other bibliographic metadata frequently contain tokens that look

like forbidden terms or like variants of preferred terms but are

*not* manuscript prose. Read every file in

`MANUSCRIPT_STATE.yaml#bibliography.paths` before scanning the

manuscript so tokens appearing in author / title / journal /

container metadata are excluded from flagging. This is a

load-bearing failure mode in the issue spec: missing this step

produces false positives that erode trust in the entire skill.

3. **Ignore inflection by default.** "cell" vs. "cells", "gene" vs.

"genes", "method" vs. "methods" — these are not drift; they are

English morphology. Flag stem-level variation only (e.g.

"cohort" vs. "cohorts" is *not* drift; "cohort" vs. "subjects"

*is*, given preferred terms are declared).

4. **Respect quoted contexts and term-as-subject contexts.** A

forbidden term inside `"quotes"` or in a passage critiquing or

defining the term itself is not an enforcement target. A sentence

like *we deliberately avoid the term "subjects"* is the author

doing exactly what the skill would want; do not flag it as a

violation.

5. **Surface, don't decide.** Undeclared near-variants — clusters of

tokens the author has not yet expressed a preference about —

are surfaced as a question: *should one of these be promoted to

`terminology.preferred`, or are they intentionally distinct?* The

skill does not pick a winner.

## Invocation discipline — when to invoke, when not

**Invoke when:**

- `MANUSCRIPT_STATE.yaml#terminology` declares preferences AND the

document is in `draft`, `revision`, or `submission` phase.

- The user explicitly asks for a terminology check.

- `argumentative-flow` has just run and the author wants to confirm

that the transformation preserved declared terms.

**Do not invoke when:**

- `terminology.preferred`, `terminology.forbidden`, and

`terminology.synonyms` are all empty — there is nothing to enforce.

- The document is in `outline` phase — terminology is not yet stable;

flagging drift here is noise.

- As a silent side-effect of another skill. The output is a report

for the author, not a precondition for another transformation.

## Inputs you should expect

- **Manuscript text** — file path(s) or pasted prose. Full prose,

including sections. If the manuscript is multi-file (e.g. Quarto

includes declared under `sections`), read each file.

- **`MANUSCRIPT_STATE.yaml`** — usually at the manuscript's root. The

`terminology.preferred`, `terminology.forbidden`,

`terminology.synonyms`, and `bibliography.paths` fields are

load-bearing.

- **Bibliography file(s)** — referenced by

`MANUSCRIPT_STATE.yaml#bibliography.paths`. Read these *before*

flagging any token in the manuscript (see constraint 2 above).

If `MANUSCRIPT_STATE.yaml` is missing entirely, stop. Tell the author

the skill has nothing to enforce against and suggest

`scriptorium:init`.

If the state file exists but its terminology lists are empty or thin,

do not silently proceed and do not invent a list from the manuscript.

Instead, **offer the default promotional-register catalog** described

below, and stop until the author accepts, edits, or declines it. The

author's declared list stays authoritative; the default is a starting

point, never an override. This preserves [[declared-work-scope]] — the

author still declares — while removing the cold start that otherwise

makes this skill useless on first contact.

## The default promotional-register catalog

Authors rarely arrive with a `terminology.forbidden` list. They arrive

with an instruction like *"drop the jargon"* or *"this sounds like

marketing."* [[promotional-register]] converts that instruction into a

declarable list, which is the point: **an instruction to avoid a

register decays across revision passes, because nothing in the loop

remembers it; the same instruction in `terminology.forbidden` is a

checkable gate.** That is the same property that makes

`constraints.preserve_citations` trustworthy — the audit is mechanical,

so the claim is falsifiable rather than asserted.

When offering the catalog, propose the subset that fits

`project.target_type`:

- **Manuscripts, theses, reviews** — the full catalog: the

transactional construction, superlative self-assessment, value

assertion in place of statement, and the high-frequency vocabulary.

- **Grants and proposals** — the same, **minus the vision-language

exemption**. Proposals are evaluated on vision plus feasibility, so

"long-term goal", "transformative", and "establish a foundation" are

appropriate in an aims page or project summary when a credible plan

backs them. Do not propose these as forbidden. See

Three exemptions apply regardless of target type, and you should say so

when offering the list rather than letting the author discover them:

1. **Discipline-precise terms.** *Robust* has a technical meaning in

statistics, *novel* in chemistry, *key* in cryptography. Flagging

these in their home field is a false positive. Ask before including

them; see [[discipline-conventions]].

2. **Significance claims proper.** A statement of why the work matters

is required work, not promotion. [[significance-positioning]] governs

these; this catalog must not touch them.

3. **Boosters at warranted strength.** The defect is a booster stronger

than its evidence, not the presence of boosters

([[esl-writers-swales-hyland]]).

One calibration note carried from the evidence: Vinkers et al. found

authors at institutions outside majority-English-speaking countries used

significantly more positive words. A filter tuned to one register will

disproportionately flag another author's ordinary prose. Propose; never

enforce.

## Conversational style

Read `meta.guidance_level` from `MANUSCRIPT_STATE.yaml` (default

`standard` if absent). Adapt framing — not the structured output —

per [[guidance-level]]:

- `terse` — open with a one-line "running terminology normalization";

emit the markdown report; no closing summary.

- `standard` — open with a sentence naming the manuscript and the

declared terminology counts (e.g. "5 preferred terms, 3 forbidden,

2 synonym mappings"); close with a one-line summary of the

findings.

- `full` — open with what this skill produces (preferred-term drift,

forbidden-term occurrences, undeclared variants, suggested

normalizations) and how to read it (which sections are

enforcement, which are questions for the author); close with

which findings to act on first and which are informational. If

running for the first time in this session, also offer

`/scriptorium:explain terminology-normalization` so the author

can learn the skill's design before reading its output.

Run the signal-based check-in once if appropriate (see the

convention note). The structured output itself is unchanged across

levels — what changes is only the framing around it. The

no-auto-apply posture is **never** relaxed based on guidance level.

## Operational protocol

Work in this order. The order matters — step 1 before step 3 is the

guard against the false-positives-on-cited-names failure mode.

1. **Read `MANUSCRIPT_STATE.yaml`.** Extract:

- `terminology.preferred` — terms the manuscript should use.

- `terminology.forbidden` — terms the manuscript should not use.

- `terminology.synonyms` — map of variant → preferred term.

- `bibliography.paths` — files to load before flagging.

- `meta.guidance_level` — framing only; see above.

- `document_phase.current` — if `outline`, decline the run.

2. **Read the bibliography file(s).** Build a set of tokens that

appear in author names, titles, journal names, and other

bibliographic metadata. Tokens in this set are excluded from

flagging, even if they match a forbidden term or a non-preferred

variant. Note in the output how many bibliographic tokens were

excluded — the count is part of the audit trail.

3. **Read the manuscript prose.** Tokenize at the stem level

(ignore inflection differences) and identify quoted regions and

term-as-subject passages so they can be excluded.

4. **Detect preferred-term drift.** For each preferred term, search

for declared synonyms (per `terminology.synonyms`) and any

undeclared near-variants. Report each variant's location and

count.

5. **Detect forbidden-term occurrences.** For each forbidden term,

list each occurrence with the surrounding sentence. Exclude

bibliographic tokens, quoted contexts, and term-as-subject

passages.

6. **Detect undeclared variants.** Cluster repeated near-variants

the author has not declared a preference for. Surface each

cluster as a question — *promote one to preferred, add a synonym

mapping, or leave as-is?*

7. **Propose normalizations.** For each preferred-term drift and

each forbidden-term occurrence, write a concrete one-pass edit

the author can apply (e.g. "Replace `subjects` with `participants`

in 4 locations: introduction L12, methods L34, results L56,

discussion L78"). Do not apply any edit.

8. **Emit the report.** Use the section headings below verbatim so

downstream skills and future orchestrators can consume the

output by structure.

## Output format

Emit a markdown document with exactly these section headings, in this

order:

```markdown

# Terminology normalization

## Summary

- Preferred terms declared: N

- Forbidden terms declared: N

- Synonym mappings declared: N

- Bibliographic tokens excluded from flagging: N

- Preferred-term drift: N variants found across M locations

- Forbidden-term occurrences: N

- Undeclared variants surfaced for author decision: N

## Preferred-term drift

(One subsection per preferred term that has detected drift. Omit

preferred terms with zero drift. For each: the preferred term, the

undeclared variant(s) found, occurrence count, and the locations.)

### `<preferred-term>`

| Variant found | Count | Locations |

|---|---|---|

| `<variant>` | N | section:line, section:line, … |

## Forbidden-term occurrences

(One row per occurrence. Quoted contexts and term-as-subject

passages are excluded — note the exclusion count separately.)

| Forbidden term | Location | Surrounding sentence |

|---|---|---|

| `<term>` | section:line | "…sentence containing the term…" |

(If any occurrences were excluded due to quoted context or

term-as-subject framing, note the count and the rationale below the

table.)

## Undeclared variants

(Clusters of repeated near-variants the author has not declared a

preference for. Each cluster is a question for the author, not an

enforcement finding.)

### Cluster <N>: <variant-a> / <variant-b> / …

- Occurrences: <variant-a> (N), <variant-b> (N), …

- Locations: …

- Question: promote one to `terminology.preferred`, add a synonym

mapping in `terminology.synonyms`, or leave as deliberate

variation?

## Suggested normalization

(Concrete one-pass edits the author can apply. Grouped by preferred

term and forbidden term. Each edit is "find / replace" with line

references. The skill does not apply these — the author does, or

invokes a follow-up edit pass.)

### Preferred-term drift fixes

- Replace `<variant>` with `<preferred>` in N locations:

section:line, section:line, …

### Forbidden-term removals

- Remove or rephrase `<forbidden>` in N locations: section:line, …

(Suggested replacement, if a `synonyms` mapping covers it:

`<preferred>`.)

## What this skill did NOT check

(Honest list. Always include the items below; add specifics from

the current run where relevant.)

- Whether a flagged variant is in fact a different concept (e.g.

"cell" and "cell-line" are distinct; the skill flags candidate

drift but the author confirms).

- US/UK English spelling variation, unless explicitly declared as

preferred / forbidden in the state file. Variety is a venue

decision, not a drift question.

- Acronym expansion and first-use enforcement — out of scope for

v0.3; covered separately when that utility lands.

- Bibliography normalization (author-name format, journal

abbreviations, etc.) — separate utility. This skill only reads

the bibliography to *exclude* its tokens from flagging.

- Stylistic-tone change. Deliberate prose variation (e.g. "stark

contrast" used for emphasis) is preserved; this skill does not

propose stylistic rewrites.

- Quoted passages and passages where a term is the subject of

discussion. These are excluded from forbidden-term enforcement.

```

## What "good output" looks like

- **Bibliography-aware.** The Summary names the count of

bibliographic tokens excluded. An audit that flags "Smith" because

Smith is a cited author has failed at step 2.

- **Inflection-blind.** "cells" and "cell" do not appear in the

drift table. Stem-level variants only.

- **Specific, location-anchored.** Never "the manuscript uses

multiple variants." Always "introduction L12, L18; methods L34."

- **Surfaces undeclared variants as questions.** The author owns

the terminology; the skill does not invent preferences.

- **Suggests, does not apply.** Every proposed edit is presented as

text the author can paste into an edit pass; the manuscript is

unchanged on disk.

- **Honest about exclusions.** Quoted contexts and term-as-subject

passages are listed by count so the author can verify the

exclusion was correct.

## What you must not do

- Modify the manuscript or the bibliography.

- Promote an undeclared variant to preferred without author

consent — even a "you probably want X" recommendation that

silently presupposes the answer.

- Flag tokens that appear only in bibliographic metadata.

- Flag inflection differences (cell/cells, gene/genes,

method/methods) as drift.

- Flag forbidden terms inside quoted passages or in passages where

the term is the subject of discussion.

- Propose stylistic rewrites beyond what the declared terminology

lists license.

- Auto-apply suggested normalizations as a follow-up step.

## Grounding

This skill is grounded in scriptorium's knowledge layer:

- [[internal-consistency]] — terminology drift is a class of

internal-consistency failure. The note frames detection

methodology: identify candidate synonym clusters, ask the author

to choose, replace. The MANUSCRIPT_STATE terminology block is

named there as the design pattern this skill consumes. The

surfaces-as-questions-not-decisions posture for undeclared

variants comes directly from that note's recommendation that the

consistency check "flag candidate-synonym clusters for the author

to resolve."

- [[style-guides]] — preferred-term enforcement is a style-guide

function. The note covers conventions across AMA (medicine), CSE

(general science), APA (psychology / social science), Chicago,

ACS, and IEEE, and is explicit that style is **venue-dependent,

not correct/incorrect**. This grounds two design choices: (a) the

preferred-terms list is project-specific and read from the state

file rather than imposed by the skill, and (b) US/UK English

variation is out of scope by default — the venue, not the skill,

decides.

A drift away from these groundings either gets the skill updated or

gets the grounding extended; never both unchanged.