Dr Cook:english Polisher

english-polisher

1. Overview

english-polisher refines academic English writing at four levels: grammar correctness, word choice precision, sentence structure clarity, and domain-specific terminology accuracy. It adapts its output to the research domain — TCM, bioinformatics, clinical, or pharmacology — applying the appropriate terminology standards for each. When a target journal is specified, english-polisher cross-references journal house style preferences for active vs. passive voice and formality level. Three polish levels are available: light (grammar and obvious errors only), standard (grammar, word choice, and structure), and deep (full academic style overhaul). The module can work on any text type: manuscript sections, abstracts, grant sections, or cover letters. It accepts text either from upstream modules via context_output.raw_text (paper-writer, grant-writer, rebuttal-writer) or directly from user-pasted input.

2. Parameters

Required

Optional

Parameter collection rule

If domain is not available from upstream context and has not been stated by the user, ask once before proceeding. Do not ask for optional parameters unless the user has explicitly mentioned a specific journal name or polish depth in their request.

3. Workflow

Step 1 — Check upstream context. Inspect context_output before asking the user for anything. If a prior module has written a raw_text field, use it as the input to polish. Inherit target_journal, domain, and language from upstream without re-asking. If no raw_text exists in context, ask the user to paste the text.

Step 2 — Collect domain if still missing. If domain is absent from upstream context and the user's message, ask once: "Which research domain? (tcm / bioinformatics / clinical / pharmacology)." Wait for the answer before proceeding.

Step 3 — Load academic style guide. Read references/academic-style-guide.md for universal grammar rules, word choice principles, sentence structure norms, and punctuation standards. Keep these active for all three passes.

Step 4 — Load domain terminology. Read references/discipline-terminology.md and extract the section matching domain. Apply rules for domain-specific errors: gene name formatting (bioinformatics), TCM term usage (tcm), participant labeling (clinical), and dose unit notation (pharmacology).

Step 5 — Cross-reference journal style (conditional). If target_journal is specified, apply journal-level voice and formality preferences. High-impact journals (NEJM, Lancet) prefer active voice in Results and Discussion; Methods accepts passive across all families. light skips style preferences; standard applies voice guidance where clearly beneficial; deep enforces all preferences throughout.

Step 6 — Apply polishing in three passes.

• Pass 1 — Grammar: Check and correct subject-verb agreement in complex noun phrases, tense consistency (past in Methods and Results, present in Introduction for established facts and in Discussion for implications), article usage (definite vs. indefinite), and parallelism in lists and compound predicates. Correct misplaced modifiers. For polish_level: light, stop after this pass.
• Pass 2 — Word choice: Replace hedging language ("it seems that" → "the data suggest"; "it could be argued" → "evidence supports"); replace colloquialisms ("a lot of" → "numerous"; "showed up" → "was observed"); sharpen imprecise verbs ("did" → "performed"; "got" → "obtained"; "looked at" → "examined"). Apply domain terminology corrections from Step 4. For polish_level: light, this pass is skipped.
• Pass 3 — Sentence structure: Break sentences exceeding 35 words into two or more sentences. Vary sentence length to improve reading rhythm — alternate shorter declarative sentences (10–15 words) with longer complex ones. Eliminate consecutive sentences beginning with "The." Ensure each paragraph has a clear topic sentence and supporting evidence following it. For polish_level: light, this pass is skipped. For polish_level: standard, apply only clear structural improvements. For polish_level: deep, enforce all norms systematically, including paragraph-level coherence review.

Step 7 — Present output. Return the polished text in a clearly demarcated block, followed by a structured change summary. The change summary lists the most significant changes by category with a before/after example for each, and an approximate count per category. See Section 4 for the exact template.

Step 8 — Offer targeted follow-up. Ask whether the user wants to focus on a specific paragraph or section for a second pass. If the user is satisfied, confirm the output is ready for the next pipeline stage (e.g., citation-checker, cover-letter-writer) and write the result to context_output.

4. Output Format

## Polished Text

[full polished text]

---
## Changes Made

**Grammar:** [N changes]
- [example: "The expressions of these genes were assessed" → "The expression of these genes was assessed" — subject-verb agreement]

**Word choice:** [N changes]
- [example: "it seems that the pathway is activated" → "the data suggest the pathway is activated"]
- [example: "a lot of studies" → "numerous studies"]

**Sentence structure:** [N changes]
- [example: 42-word sentence split into two sentences for clarity]

**Terminology corrections:** [N changes — only if domain issues found]
- [example: "acupuncture point ST36" → "acupoint ST36" — tcm convention]

If no changes were made in a category, omit that category header from the summary. Always include an approximate total: "~N changes across all categories."

5. context_output

Reads from upstream

Writes to output

{
  "module": "english-polisher",
  "domain": "<inherited or collected>",
  "target_journal": "<inherited or null>",
  "language": "en",
  "raw_text": "<polished text — overwrites upstream raw_text>",
  "summary": "<brief description of changes: N grammar, N word choice, N structure corrections>",
  "status": "success",
  "error_message": "string | null",
  "parameters": {
    "polish_level": "<collected or default: standard>"
  }
}

Downstream readers of raw_text: citation-checker, cover-letter-writer. Downstream readers of summary: cover-letter-writer (for context on the manuscript's current state).

6. References

See references/ for:

• academic-style-guide.md — Grammar rules, word choice principles, sentence structure norms, and punctuation standards applicable to all academic English
• discipline-terminology.md — Domain-specific terminology requirements and common errors for tcm, bioinformatics, clinical, and pharmacology