/write-scientific-manuscript

name: write-scientific-manuscript
description: >-
  Diagnose and repair the clarity and logic of manuscript prose, journal-agnostic. Use when a
  passage is technically correct but hard to follow: buried topic sentences, missing logical
  bridges, ambiguous referents, abstract noun chains, overloaded sentences, incomplete comparisons
  with no stated dataset or metric or direction, scope qualifiers placed too far from the claim,
  and invented or inflated terminology that should have been an ordinary word. Also covers writing
  for a broad scientific reader without losing precision, section-by-section logic patterns,
  paragraph-level reverse outlines, and keeping observation separate from interpretation. This is
  the layer between structure and punctuation: use manuscript-optimizer when the claim hierarchy
  itself is unstable, and scientific-prose-style for the final sentence-level pass.

Write Scientific Manuscripts

Make the science easy to follow before making the prose elegant. Optimize in this order: scientific logic, reader comprehension, evidential precision, then style.

Where this sits

This skill owns clarity and logic diagnosis. It carries no house style and no punctuation budget.

• `manuscript-optimizer` when the problem is above the prose: the claim hierarchy, evidence chain,

or figure logic is unstable. Fix that first. Polishing a paragraph whose scientific role is wrong wastes the edit.

• `scientific-writing` when a section needs drafting or rewriting into full paragraphs, or when the

task names a citation style or a reporting guideline.

• `anti-defensive-writing` after the passage logic is settled, when the text reads like an audit

report, a rebuttal or a self-critique.

• `scientific-prose-style` last, for punctuation and rhythm. This file deliberately carries no

em-dash or semicolon rule. That skill owns both, and its cap for each is at most one per paragraph and none in the abstract.

• `results-section-revision` when only Results subsection flow and paragraph openings need repair.
• `review-article-architecture` when the piece is a Review, survey, or Perspective.
• `rebuttal-response` when the prose is a reply to reviewers rather than manuscript text. The

claim-calibration ladder there is the same one used below.

Establish the intended meaning

Before rewriting, determine:

1. What single point must the reader understand? 2. What information must the reader already know for that point to make sense? 3. What evidence supports it? 4. What inference is justified, and what remains uncertain? 5. Why does the point matter at this location in the manuscript?

Do not polish a sentence whose scientific role is unclear. If necessary, briefly diagnose the logic before drafting.

For file-based revision, identify the authoritative version and preserve citations, figure references, terminology, numbers, and formatting. Read the file before editing it, and rebuild the document when the edit could disturb layout, floats, or cross-references.

Write for a broad scientific reader

Clarity and breadth are different repairs. The rules below make a passage followable; they do not turn a technical framing into one a broad peer (大同行) can use. In the broad positions defined in the Readers section of `paper-workflow`'s `references/section-contracts.md` (the Abstract, the opening and close of the Introduction, Results subsections and Discussion), check the framing first:

• by the end of the second sentence the reader faces a specific problem they recognise as theirs,

stated in their terms, not a truism about the field or the authors' task called important;

• the method is introduced by what it lets a biologist find or predict, and only then by how;
• findings say what was predicted or recovered, compared with what the biologist relies on where the

Results contain that comparison;

• a metric is named only with what it measures, and a number appears in units the reader can judge

(keep the numbers that show the scale of the evidence and the size of the gain);

• a scientist from another field could restate the problem, the finding and why it matters.

Do not delete technical terms to look accessible. Place each after the function it serves, and keep the technical detail in Results and Methods.

Then apply the passage rules:

• Assume intelligence but not local project knowledge.
• Introduce the biological or methodological problem before project-specific machinery.
• Define an uncommon term when first needed, not several paragraphs earlier.
• Make referents explicit. Replace ambiguous `this`, `these`, and `it` when the reader could plausibly choose the wrong antecedent.
• State the logical connection instead of asking the reader to infer it.
• Prefer a concrete subject and verb over abstract noun chains.
• Preserve necessary technical detail, but move secondary detail away from the sentence carrying the main claim.

Broad accessibility does not mean removing precision. Keep exact distinctions when they change the scientific meaning.

Put logic first

Give each paragraph one main job. Use this default progression when applicable:

1. **Topic sentence:** state the paragraph's point or function. 2. **Necessary setup:** provide only the context needed to understand the evidence. 3. **Evidence or reasoning:** report the relevant result, comparison, or limitation. 4. **Interpretation:** explain what the evidence means at the supported strength. 5. **Connection:** show why the next paragraph or section follows.

Do not force all five elements into every paragraph. Do require the first sentence to orient the reader. Avoid paragraphs that begin with implementation detail and reveal their purpose only at the end.

Build explicit bridges between adjacent claims. A valid sentence can still be misplaced if it does not answer the question raised immediately before it.

Read [section-logic.md](references/section-logic.md) when restructuring a section, an abstract, o