write-scientific-manuscript

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:

What single point must the reader understand?
What information must the reader already know for that point to make sense?
What evidence supports it?
What inference is justified, and what remains uncertain?
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:

Topic sentence: state the paragraph's point or function.
Necessary setup: provide only the context needed to understand the evidence.
Evidence or reasoning: report the relevant result, comparison, or limitation.
Interpretation: explain what the evidence means at the supported strength.
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 when restructuring a section, an abstract, or a full manuscript.

Paragraph boundaries and displayed mathematics

Judge a paragraph by its scientific job, not its sentence count. A concise finding or definition can stand alone. A paragraph containing only "Full details are provided in Supplementary Note 2" usually belongs at the end of the related scientific paragraph, as a sentence or parenthetical reference. Retain its destination and any necessary scope; do not delete the reference merely to remove the navigation paragraph. Merge adjacent short paragraphs only when they serve the same job. Run-in Methods headings can mark distinct procedures and should not be removed just because the following text is short.

A display does not itself start a new paragraph. Keep an introduction, the formula and its immediate symbol explanation together when they form one sentence or reasoning unit. In LaTeX, ordinary source line wrapping does not split a paragraph; a blank line or \par does. Preserve punctuation through the display and start a new paragraph when the explanation ends or a new concept begins. Do not remove every blank line around every formula: a new procedure after a display can be a legitimate paragraph boundary.

For example, these fragments belong to one paragraph:

The response score is
\[
S(q,d)=-D(q,d),
\]
where $D$ denotes the response distance.

Equation numbering and page placement are typesetting choices handled by scientific-writing's references/latex-layout.md. Source scans may identify navigation-only paragraphs or suspicious blank lines, but semantic review decides each change; do not batch-merge by length or regex alone.

Prefer the simplest accurate language

Use familiar scientific words when they express the same meaning.
Prefer short, direct constructions, but vary sentence length naturally.
Keep one principal claim per sentence unless two claims are inseparable.
Use active voice when it makes the actor or logic clearer; use passive voice when the procedure or result is the natural focus.
Remove throat-clearing, duplicated meaning, ornamental transitions, and empty intensifiers.
Avoid compressed strings of nouns and stacked modifiers.
Make the thing that acts the grammatical subject. "The experiments further reveal a clear boundary set by information availability" becomes "Information availability sets a boundary", followed by the boundary itself.
Do not replace a clear ordinary word merely to sound more sophisticated.
Do not use a fragmentary series of very short sentences when the causal or contrastive relation is clearer in one well-formed sentence.

Aim for the mature, restrained vocabulary common in strong general-science journals. Treat Nature style as clarity, economy, reader guidance, and calibrated claims, not as a list of fashionable words.

Read language-guide.md when performing sentence-level revision or terminology cleanup.

Do not invent terminology casually

Use a new label only when all of the following are true:

the concept is genuinely distinct from established terms;
the distinction is important more than once;
existing terminology would be misleading or unwieldy;
the label can be defined in one direct sentence;
the same label will be used consistently afterward.

Otherwise, describe the phenomenon directly. Do not capitalize, hyphenate, abbreviate, or name an ordinary analytical step to manufacture novelty. A hyphenated modifier coined for the paper is the most common case: "deployment-available biological knowledge" becomes "biological knowledge available before profiling". Field terms readers already use, such as "cell-type-aware", stay. scientific-prose-style's scripts/ai_tells.py lists candidate compounds, and its references/ai-tells.md gives the other tells. Search the manuscript and, when needed, the relevant literature before asserting that a term is standard or introducing a replacement.

Preserve established field terminology even when it is less elegant than a newly invented alternative. If the source uses an unclear coined term, explain the issue and propose a conventional replacement rather than silently creating another term.

Calibrate claims to evidence

Report observations before interpretations.
Use show for a result directly established by the analysis; use suggest, is consistent with, or may reflect for supported interpretations.
Do not turn association, sensitivity, prediction, or diagnostic evidence into mechanism or causation.
Scope conclusions to the evaluated datasets, tasks, conditions, models, or search space when needed.
Avoid universal, optimal, robust, general, fundamental, comprehensive, and state-of-the-art unless the design supports the full claim.
Distinguish an absence of evidence from evidence of absence.
Retain negative or mixed results and explain what they narrow.

Never improve flow by deleting a scientifically important limitation or qualifier. Instead, place the qualifier where it constrains the claim without obscuring the main message. The reverse holds too: never resolve an ambiguity by adding a qualifier when a precise definition would remove it ("the four labels denote dataset regimes", not a sentence about what they do not mean).

Revise in passes

Use this order for substantial revision:

Scientific function: identify the role of each section and paragraph.
Argument structure: reorder, merge, or split material so each claim follows from the preceding question or evidence.
Reader prerequisites: supply missing definitions and remove premature detail.
Claim boundaries: align verbs and qualifiers with the evidence.
Terminology: use conventional terms consistently and remove unnecessary labels or abbreviations.
Sentence clarity: simplify syntax, repair referents, and remove redundancy.
Continuity: check transitions, repeated claims, citation placement, and figure callouts.
Read-aloud pass: revise sentences that remain difficult to parse on first reading.

Do not begin by swapping individual words if the paragraph's logic or order is wrong.

Adapt to the manuscript section

Each position has its own job and acceptance criteria, defined once in paper-workflow's references/section-contracts.md. Read the entry for the section being revised, and accept a passage edit only when the passage still meets it. section-logic.md gives the paragraph-level patterns for applying those contracts.

Two positions change what passage repair means:

Methods: fix ambiguity, not rhythm. Exact, reproducible description outranks flow; do not merge or compress definitions to make them read better.
Figure legends: the legend must stand without the Results text, and a clarity edit never adds interpretation.

Match the requested output

Unless the user requests prose only, provide:

a short diagnosis of the main logical or language problems;
complete ready-to-use revised text;
brief notes only for choices that materially affect scientific meaning.

When revising a whole section, preserve LaTeX, citation keys, italicization, symbols, and figure references unless asked to change them. Do not fabricate citations or silently drop citation placeholders.

When auditing, separate:

Must change: incorrect logic, unsupported claims, ambiguous scientific meaning, inconsistent terminology, broken references, or language that materially misstates the evidence.
Recommended: substantial improvements to reader comprehension or narrative continuity.
Optional: preference-level polishing.

If the user asks only for mandatory changes, report only those and explicitly state when none remain.

Provenance: distilled from a completed revision cycle on a computational-biology manuscript, then generalized. Cross-references adapted to this repository's skills.