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 (the first two are scope guards the author can override; see Guards and overrides):

• 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.

Guards and overrides

This skill's guards are declared in manifest.yaml and follow [[author-authority]]: the author decides what the skill may do. Both guards are scope guards with default refuse.

• terminology-lists-required. Fires when MANUSCRIPT_STATE.yaml is missing, or when all three terminology lists are empty and the author declines the default catalog (see Inputs below). State the concern and its source in one line: "MANUSCRIPT_STATE.yaml declares no terminology preferences to enforce; the skill offers its default catalog rather than inventing a list (terminology-lists-required; source: [[declared-work-scope]])." Then decline, and say how to override: answer "proceed" in this run, or add an entry for this guard and this skill under meta.overrides. On override, run undeclared-variant detection only (protocol steps 2, 3 and 6, asking for the bibliography files if there is no state file): the clusters are surfaced as questions, the enforcement sections are left empty with a note that nothing was declared, and no preferred or forbidden list is invented.
• outline-phase. Fires when document_phase.current is outline. State the concern and its source in one line: "The manuscript is at outline phase; there is not yet enough declared prose for this skill to work on (outline-phase; source: [[declared-work-scope]])." Then decline, naming the same two override routes. On override, run the full protocol and note in the Summary that terminology at outline phase may not yet be stable.

For each guard, the first of these decides: the author's answer in this run, in either direction; an entry under meta.overrides naming the guard and this skill (or "*"); the default, refuse. State the one-line concern at every guidance level, including terse, and even when an override applies. When the run proceeds past a guard, the output carries an Overrides applied: line listing the guard ids (see Output format); otherwise the line is omitted. The consent rules (never apply an edit, never promote a variant without the author) are not guards and are unaffected by any override.

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, the terminology-lists-required guard applies: by default, 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. If the lists are empty and the author declines, the terminology-lists-required guard applies; if they are thin, run against what is declared. 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 [[grant-writing-evidence]] and [[nih-significance-patterns]]. The vision exemption does not extend to novel: NIH's Innovation language says a project "not applying novel concepts or approaches may be of critical importance for the field", which is a reason not to push authors toward the word in grant prose ([[significance-positioning]]).

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]]).

When the offer includes the high-frequency vocabulary, keep the note's grounding split visible. Present as corpus-grounded only the 13 entries [[promotional-register]] lists as Vinkers- or Kobak-backed (robust, novel, innovative, unprecedented, crucial, pivotal, seamless, revolutionize, transformative, leverage, showcase, underscore, delve). Label the other 8 (cutting-edge, state-of-the-art, world-class, key, landscape, ecosystem, paradigm, testament) as practice-derived. Date the list to the note's last update and say that LLM marker words drift (Kobak et al. 2025; Hubarava & Ineichen 2026), so the default needs periodic refreshing from the note.

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.
   • meta.overrides — see Guards and overrides.
   • document_phase.current — if outline, the outline-phase guard applies (decline unless overridden).
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:

# Terminology normalization

Overrides applied: <guard ids>

(Only when this run proceeded past a scope guard, through a per-run
answer or `meta.overrides`. Omit the line otherwise.)

## 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.
• [[promotional-register]] — source of the default catalog offered when the declared lists are empty or thin. The note separates corpus-grounded vocabulary (Vinkers et al. 2015; Kobak et al. 2025) from practice-derived entries and constructions, and records the three registers the catalog must not touch.
• [[significance-positioning]] — grounds the exemption for significance claims proper, and NIH's Innovation language as the reason not to push "novel" in grant prose.
• [[author-authority]] — the two scope guards are defaults the author can override, per run or under meta.overrides.

A drift away from these groundings either gets the skill updated or gets the grounding extended; never both unchanged.