Deterministic acronym hygiene check: writer-side fix, reviewer-side advisory
Discussion #848 reports two acronym failure modes common in drafted text: an acronym defined more than once, or never defined. ARS has scattered prompt and checklist guidance on this (abstract_bilingual_agent.md:130, citation_compliance_agent.md:318, the abstract template and guide checklists, intro_title_rhetoric_guide.md:92) but no deterministic manuscript-wide check. writing_quality_check.md sections A-E carry no acronym rule and the formatter_agent Final Quality Checklist has none.
Scope. One deterministic script, scripts/check_acronyms.py (stdlib only, no model call, never edits the manuscript), run by the caller and consumed on two sides.
v1 rules (journal copyediting defaults; author and venue requirements take precedence per writing_quality_check.md "Priority and scope"):
- First use is defined: full form, then the acronym in parentheses; later uses take the acronym only.
- Definition scopes are independent: the body, the English abstract, and the Chinese abstract each define separately. The Chinese form
全稱(English full form, ABBR)is recognized; an unrecognized definition convention yields a disclosed coverage limit, not an "undefined" finding. - No repeated definition inside one scope.
- Allowlist of acronyms needing no definition: a repo default (SI units, DNA, and similar) plus an optional user list. The allowlist exempts rules 1 and 3 only. Discipline lists are welcome as fixtures, not as a profile framework.
Token rules. A candidate is 2-6 characters, uppercase-led, mixed case and digits allowed (eGFR, qPCR, H2O excluded by a chemical-formula heuristic). Plural and possessive forms (RCTs, RCT's) normalize to the base. Exclusions, applied without changing source line coordinates: code spans and fences, HTML comments including <!--ref:...--> and <!--anchor:...--> markers, metadata and scoring sections, headings, reference list, tables, figures, captions and notes, author initials in citations (Smith JA), APA group-author first-citation brackets (World Health Organization [WHO]), and single-letter or two-letter statistical symbols (M, SD, N, F). Whole-token matching only (no AI inside AIDS).
Deferred to a later slice, tracked here: spell-out threshold (fewer than 3 uses), one-term-one-acronym consistency, table and figure self-containment.
Consumers.
- Writer side. The caller runs the script on the assembled draft after
draft_writer_agentStep 3 and passes the report to the writer; the writer cannot run it (Bucket A, Bash denied by the write-scope guard). During initial drafting the writer resolves applicable findings. During a Phase 6 revision round it corrects only inside already-authorizedwill_addresstargets; other findings stay advisory. The abstracts are checked after Phase 5b and corrected byabstract_bilingual_agent. Contract-mode drafting (Phase 4b) must be wired explicitly since it receives only its subsection.writing_quality_check.mdgains a section F pointing at the script. Standaloneacademic-papermodes get the same caller-side hook. - Reviewer side. The caller attaches the report to the Editorial Decision Letter as a separate block after synthesis validation. It is not an input to any reviewer seat, not a weakness, consensus item, required or suggested revision, or roadmap entry; the synthesizer originates no comment from it; sprint contract dimensions and failure conditions are unchanged. The letter's
R<n>grammar is preserved.
Advisory contract. Findings impose no response obligation and affect neither decisions nor continuation. Execution failure (no interpreter, unreadable input, unsupported format, unrecognized scope) produces an explicit not-checked or partial-coverage artifact, never a clean result; the mechanism is registered in shared/contracts/degradation_registry.json with its pinned inventory and tests.
Output. Deterministic JSON + Markdown, stable ordering; each finding carries scope, source line, rule id, acronym, expansion when present, and occurrence count.
Test material. Synthetic fixtures first, one per token-rule example above. Excerpts contributed in #848 are added as fixtures with credit; the de-identification caution is stated in that thread.
Acceptance.
- Script + unit and fixture tests; test files registered in
scripts/_ci_pytest_manifest.toml. - Tests prove: source-line fidelity, deterministic ordering, clean-versus-not-checked distinction, manuscript bytes unchanged by the checker, panel decision and re-review letter extraction unchanged with the attachment present.
- Two PRs in order. PR 1: script, section F, writer-side and abstract-side caller hooks, registry entry. PR 2: reviewer-side attachment; touches the synthesizer canonical fragment and its inline mirror (
check_reviewer_sprint_prompt_sync.py), the decision template (check_reviewer_finding_contract.py,check_670_revision_roadmap_integration.py), and any pipeline surface undercheck_pipeline_boundary_semantics.pyhashes; pins updated in the same commit. - CHANGELOG entry crediting @reiropke for the proposal and any fixtures.
Refs #848.
Source: Imbad0202/academic-research-skills