seandavi/scriptorium/terminology-normalization

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.

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

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

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

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

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

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