scientific-writing · diff
git:20260905.3e49039 to git:20261001.bf5afd6
86 added, 109 removed. Audit A to A.
---
name: scientific-writing
- description: Draft or edit scientific prose while preserving its claims and evidence. Use when writing manuscript sections, proposal narratives, rebuttals, or response letters, or when checking sentence-level clarity and style.
+ description: Draft or revise scientific prose without changing its claims. Use for manuscript sections, proposal narratives, rebuttals, response letters, or a sentence-level clarity review.
---
# Scientific Writing
- Use this as the single scientific-writing skill for both Codex and Claude Code. It covers two related modes of work:
-
- - **Drafting and revision** — produce a manuscript or rebuttal from authoritative artifacts and iterate it through review-revise loops.
- - **Sentence-level writing review** — audit existing prose for clarity, voice, sentence architecture, terminology consistency, and numerical integrity, without changing the underlying science.
+ One scientific-writing skill for Codex and Claude Code. It has two modes that share one role set and one set of hard rules:
- The two modes share the same role set and the same hard rules. Pick the entry point that matches the request; the workflow then routes accordingly.
+ - **Drafting and revision**: produce a manuscript section or rebuttal from authoritative artifacts and improve it through review and revision loops.
+ - **Writing review**: audit existing prose for clarity, voice, sentence structure, terminology, and numerical consistency without changing the science.
## Routing Boundary
- - Use this skill when the requested output is manuscript prose or a prose-
- quality review that preserves the underlying scientific claims.
- - Use `/bio-logic` when the main question is whether a method, design, causal
- claim, or interpretation is scientifically justified.
- - Use `/manuscript-review-council` for journal-style peer review or a
- multi-reviewer critique. Route the resulting evidence-backed revisions back
- here.
- - Generic requests containing only “write” do not establish scientific-writing
- intent and should remain unmatched.
+ - Use this skill when the output is manuscript prose, or a prose-quality review that keeps the scientific claims as they are.
+ - Use `/bio-logic` when the question is whether a method, design, causal claim, or interpretation is scientifically justified.
+ - Use `/manuscript-review-council` for journal-style peer review or a multi-reviewer critique, then bring the evidence-backed revisions back here.
+ - Use `/proposal-review` to critique a funding proposal; use this skill to write or revise its narrative.
+ - A request that only says "write" does not establish scientific-writing intent.
## State Assumptions First
Before drafting or reviewing, state:
- manuscript mode: new draft, revision, rebuttal, review response, section rewrite, or writing review
- - review mode when this is a writing review: `full-review`, `section-review`, `targeted`, or `interactive` (see below)
+ - review mode for a writing review (see below)
- target venue or formatting target when known
- authoritative artifacts available
- missing artifacts that block specific claims
- If a required input is missing, name the gap and keep the prose conservative.
+ If a required input is missing, name the gap and limit the affected claim to what the evidence shows.
## Review Modes
- When the request is a writing review of existing prose, choose one mode:
-
| Mode | Trigger | Behavior |
|---|---|---|
- | `full-review` | "review my manuscript", "writing review" | Run all five prose-quality audits on the whole document and emit a structured report. Default when ambiguous. |
- | `section-review` | "review the Introduction", "check the Discussion" | Run all five audits on a single section. |
- | `targeted` | "fix passive voice", "strip the clutter" | Run only the requested audit pass(es). |
- | `interactive` | "walk me through improving this" | Go paragraph by paragraph: show original, show revision, explain changes, wait for confirmation. |
-
- Both drafting and review work share the same auditable artifact set (plan, draft, citation audit, review notes, revision notes).
+ | `full-review` | "review my manuscript", "writing review" | Run all five prose audits on the whole document. Default when the request is ambiguous. |
+ | `section-review` | "review the Introduction" | Run all five audits on one section. |
+ | `targeted` | "fix passive voice", "strip the clutter" | Run only the requested audit passes. |
+ | `interactive` | "walk me through improving this" | Go paragraph by paragraph: original, revision, reason; wait for confirmation. |
## Instructions
- 1. Inventory the artifact bundle before writing or reviewing. See `references/workflow.md`.
- 2. Choose a runtime pattern:
- - On Codex, use spawned subagents when available, otherwise run the same roles sequentially.
- - On Claude Code, use worker agents when available, otherwise run the same roles sequentially.
- 3. Split the run into these core roles:
- - planner
- - methods-writer
- - structure-writer
- - writer
- - citation-auditor
- - reviewer
- - reviser
- 4. **For drafting work**: produce content in a fixed order — Methods, structure outline, manuscript prose, citation audit.
- 5. **For writing-review work**: run the prose-quality audits described in `references/writing-quality.md`. Five passes, applied in order: clutter; voice and verbs; sentence architecture; terminology and keywords; numbers and citations. Each finding carries a severity tag (CRITICAL / MAJOR / MINOR) and a concrete revision — never a vague "consider improving" suggestion.
- 6. Run an explicit `review -> revise -> review` loop until one of these is true:
+ 1. Inventory the artifact bundle before writing or reviewing. See [references/workflow.md](references/workflow.md).
+ 2. Split the run into the roles in [Role Set](#role-set). Use subagents when the platform offers them; otherwise run the roles in sequence and keep their outputs separate.
+ 3. **Drafting**: write in this order: Methods, section outline, manuscript prose, citation audit.
+ 4. **Writing review**: run the five audits in [references/writing-quality.md](references/writing-quality.md) in order. Each finding carries a severity tag and a concrete revision.
+ 5. Apply the [Manuscript Rules](#manuscript-rules) to every draft and every review.
+ 6. Run a `review -> revise -> review` loop until one of these is true:
- no fixable major issues remain
- only minor edits remain
- - the remaining issues require missing evidence
- - another loop would only repeat the same findings without material improvement
- 7. For manuscript figures, review the figure/caption pair as evidence, not decoration:
- - keep the figure title and interpretation in the caption; remove in-plot titles/subtitles from graphics
- - make the caption state the finding, comparison context, sample size or cohort, units, uncertainty, and statistical test when relevant
- - prefer direct labels, panel labels, axis labels, and concise legends over legend-heavy graphics
- - flag 3D, pie charts, dual y-axes, heavy grids, decorative gradients, and overloaded multi-series plots as revision issues
- - recommend a sentence/table when the figure shows only one or two values, small multiples for many series, slopegraphs for before/after contrasts, and sparklines for compact trend context
- 8. Keep intermediate artifacts auditable: plan, methods draft, outline, manuscript draft, citation audit, review notes, and revision notes.
- 9. Validate citations before finalizing. Use `/crossref-lookup` when DOI or title checks are needed.
- 10. Return unresolved evidence gaps explicitly instead of smoothing them over.
-
- ## Prose-Quality Audits
-
- When the reviewer pass runs, it applies five sequential audits. The full audit tables, examples, and constraints live in `references/writing-quality.md`. Summary:
+ - the remaining issues need evidence that is not available
+ - another loop would repeat the same findings without improvement
+ 7. Review each figure and its legend together:
+ - remove in-plot titles; the legend opens with a short title that names what is shown, not the result
+ - the legend states what is plotted: panels, axes and units, what colours, shapes, and lines encode, n per group, what error bars or intervals show, and the statistical test; the finding belongs in the Results text
+ - plots are greyscale by default; use colour only when it encodes information (a category the reader must tell apart, the one highlighted finding, an ordered or signed quantity), use a colourblind-safe palette, and never make colour the only encoding
+ - prefer direct labels and panel labels over large legends
+ - flag 3D effects, pie charts, dual y-axes, heavy grids, decorative gradients, and overloaded multi-series plots
+ - suggest a sentence or table when a figure shows only one or two values, small multiples for many series, and slopegraphs for before/after contrasts
+ 8. Keep intermediate artifacts auditable: plan, Methods draft, outline, manuscript draft, citation audit, review notes, and revision notes.
+ 9. Validate citations before finalizing. Use `/crossref-lookup` for DOI and title checks.
+ 10. Report unresolved evidence gaps explicitly instead of smoothing them over.
- 1. **Clutter** — strip dead-weight phrases, dead openers, and redundancy.
- 2. **Voice and verb vitality** — convert obscuring passive constructions to active; resurrect smothered verbs ("provides a description of" → "describes"). Passive is acceptable when the actor is unknown or when Methods house style requires it.
- 3. **Sentence architecture** — flag buried predicates (>~12 words between subject and verb), use colons/dashes/semicolons for compression, vary sentence length.
- 4. **Terminology and keywords** — enforce the Banana Rule (don't paraphrase defined terms), audit acronym definitions at every first use (Abstract, body, every legend), reject author-convenience acronyms.
- 5. **Numbers and citations** — check N, percentages, and significant figures across Abstract, text, tables, and figures; flag "telephone-game" statistics cited only through reviews or textbooks.
+ ## Manuscript Rules
- Output: every finding includes file/section reference, original text, concrete revision, the audit pass it triggers, and a severity tag.
+ These rules apply to drafting, revision, and review. Flag violations as MAJOR findings.
- ## Severity Tags
+ - State each supported claim once, plainly. Do not follow every claim with a caveat sentence.
+ - State each limitation once, where it applies (usually one limitations paragraph in the Discussion), and do not repeat it across sections.
+ - When the data support a comparative claim ("A recovered more genomes than B"), state it directly with the numbers. Do not soften it with stacked qualifiers.
+ - Never explain away a result with a reason that has not been checked. If the cause is unknown, say that it is unknown or name the analysis that would test it.
+ - Figure and table legends describe what is shown; they do not restate results or interpretation.
+ - Keep implementation details out of Results: script names, file formats, internal flags, refactors, and runtime bookkeeping. Put what a reader needs to reproduce the work in Methods.
+ - Do not use an em dash as the default connector. Use a period, comma, colon, semicolon, or parentheses.
- Used by both reviewer and reviser. Reviser addresses CRITICAL and MAJOR first.
+ ## Prose-Quality Audits
- - **CRITICAL** — actively misleads the reader (wrong number, term inconsistency implying a different variable, passive voice hiding important accountability).
- - **MAJOR** — significantly impairs clarity (buried predicates, heavy nominalization, dense clutter, inconsistent acronym definitions, secondary-source statistics).
- - **MINOR** — worth fixing but does not impede understanding.
+ The reviewer applies five audits in order. Tables, examples, and constraints are in [references/writing-quality.md](references/writing-quality.md).
- ## Quick Reference
+ 1. **Clutter**: remove dead-weight phrases, empty openers, and redundancy.
+ 2. **Voice and verbs**: change passives that hide the actor to active voice; turn nominalizations back into verbs ("provides a description of" becomes "describes"). Passive is fine when the actor is unknown or when the venue requires it in Methods.
+ 3. **Sentence architecture**: flag subjects separated from their verb by more than about 12 words, and paragraphs of uniform sentence length.
+ 4. **Terminology**: keep defined terms fixed (the Banana Rule), define each acronym at first use in the Abstract, main text, and each legend, and reject acronyms invented for the authors' convenience.
+ 5. **Numbers and citations**: check N, percentages, and significant figures across Abstract, text, tables, and figures; trace statistics cited only through reviews back to the primary source.
- | Task | Action |
- |------|--------|
- | Plan a writing run | audit artifacts, mode, venue, and blockers before prose |
- | Draft a manuscript | follow Methods -> outline -> prose -> citation audit |
- | Improve quality | run reviewer and reviser loops until quality gates pass or evidence runs out |
- | Validate citations | `/crossref-lookup` |
+ Every finding gives the section reference, original text, concrete revision, audit pass, and severity: **CRITICAL** (misleads the reader), **MAJOR** (impairs clarity or breaks a Manuscript Rule), or **MINOR** (worth fixing, does not impede understanding). The reviser handles CRITICAL and MAJOR first.
## Input Requirements
- manuscript request, brief, or target section
- - authoritative manuscript artifacts such as prior drafts, notes, protocols, code, logs, or structured results
+ - authoritative artifacts such as prior drafts, notes, protocols, code, logs, or structured results
- bibliography inputs such as `.bib` files, DOI lists, or trusted reference notes
- venue instructions when available
## Output
- manuscript draft or revised section in paragraph prose
- auditable planning, review, and revision notes
- citation audit results when citation work is in scope
- explicit unresolved evidence gaps
## Quality Gates
- - [ ] claims stay within the supplied evidence
+ - [ ] claims stay within the supplied evidence, and supported claims are stated without repeated caveats
+ - [ ] each limitation appears once
+ - [ ] no result is explained by an unchecked cause
- [ ] Methods trace to real artifacts rather than inference
- [ ] numbers in prose match structured summaries or tables
- - [ ] manuscript figures use captions rather than in-plot titles and captions state the finding, context, units, uncertainty, and test where relevant
- - [ ] figure text calls out misleading or low-data-ink displays instead of treating them as neutral style choices
+ - [ ] legends describe panels, axes, units, encodings, n, error bars, and tests, and do not restate results
+ - [ ] figures are greyscale unless colour encodes information, and colour is never the only encoding
+ - [ ] Results contain no implementation details that belong in Methods
- [ ] citations are validated, inherited from trusted sources, or marked for follow-up
- - [ ] reviewer findings are either fixed or carried forward as blocked gaps
+ - [ ] reviewer findings are fixed or carried forward as blocked gaps
## Role Set
+ Full contracts are in [references/agent-prompts.md](references/agent-prompts.md).
+
- `planner`: audits the artifact bundle and defines the writing order
- `methods-writer`: drafts Methods from source artifacts only
- - `structure-writer`: creates the section skeleton and figure/table plan
- - `writer`: drafts paragraph prose from the plan and available evidence
+ - `structure-writer`: creates the section outline and figure/table plan
+ - `writer`: drafts paragraph prose from the plan and the evidence
- `citation-auditor`: checks citation correctness, placement, and bibliography safety
- - `reviewer`: produces a scientific review report with revision priorities
- - `reviser`: applies only evidence-backed fixes and carries forward blocked issues explicitly
+ - `reviewer`: reviews scientific content and prose quality and sets revision priorities
+ - `reviser`: applies evidence-backed fixes and carries blocked issues forward
## Hard Rules
- Do not invent data, experiments, citations, reviewer comments, or bibliography entries.
- Do not transcribe numbers from memory when structured tables, JSON, CSV, or prior manuscripts exist.
- - Do not silently mutate `.bib` files; describe or stage citation edits explicitly.
- - Final manuscript text should be paragraph prose, not bullet outlines, except for planning artifacts.
- - If reviewer feedback would require new evidence, say so directly.
- - **Do not alter scientific content during a writing review.** Improve delivery, not substance. Flag a claim that looks wrong rather than rewriting it.
- - **Respect disciplinary and journal conventions.** Some fields require passive voice in Methods; some journals have specific style rules. Ask about the target venue when it is not stated.
- - **Preserve author voice.** Aim for clarity, not homogeneity. A sentence that is clear and effective despite breaking one of the audit rules should be left alone.
- - **Be specific.** Every reviewer finding must include the original text and a concrete revision. "Consider tightening the language" is not an acceptable finding.
+ - Do not edit `.bib` files silently; describe or stage citation edits.
+ - Final manuscript text is paragraph prose; bullets belong only in planning artifacts.
+ - If reviewer feedback needs new evidence, say so directly.
+ - In a writing review, change delivery, not substance. Flag a claim that looks wrong instead of rewriting it.
+ - Respect field and venue conventions, such as passive voice in Methods. Ask about the venue when it is not stated.
+ - Preserve the author's voice. Leave a clear sentence alone even if it breaks an audit rule.
- ## Examples
+ ## Example
- ### Example 1: Section Rewrite With Review Loop
+ Section rewrite with a review loop:
1. inventory the artifact bundle and identify missing evidence
- 2. draft the requested section in paragraph prose
- 3. run reviewer and reviser passes until the remaining issues are minor or evidence-blocked
- 4. return the revised section plus unresolved gaps
-
- ### Example 2: Citation Check
-
- Use `/crossref-lookup` for DOI validation, title matching, and bibliography audits before finalizing the manuscript.
+ 2. draft the section in paragraph prose
+ 3. run reviewer and reviser passes until the remaining issues are minor or blocked by missing evidence
+ 4. return the revised section and the unresolved gaps
## Troubleshooting
**Issue**: Reviewer feedback asks for experiments, citations, or data that are not in the artifacts.
- **Solution**: Mark the issue as blocked by missing evidence and keep the claim conservative.
+ **Solution**: Mark the issue as blocked by missing evidence and limit the claim to what the artifacts show.
**Issue**: The draft keeps changing wording without resolving the same major issue.
- **Solution**: Stop the loop, report the repeated unresolved issue, and explain what missing artifact would be needed to fix it.
+ **Solution**: Stop the loop, report the repeated issue, and name the artifact that would resolve it.
## References
- - Workflow and checkpoints: `references/workflow.md`
- - Role contracts: `references/agent-prompts.md`
- - Prose-quality audits, severity tags, dead-weight phrase tables, banana rule, telephone-game audit: `references/writing-quality.md`
- - Supporting skills to invoke when available: `references/supporting-skills.md`
- - Reporting and citation shortcuts: `references/reporting-shortcuts.md`
+ - Workflow and checkpoints: [references/workflow.md](references/workflow.md)
+ - Role contracts: [references/agent-prompts.md](references/agent-prompts.md)
+ - Prose audits, phrase tables, Banana Rule, citation tracing: [references/writing-quality.md](references/writing-quality.md)
+ - Supporting skills: [references/supporting-skills.md](references/supporting-skills.md)
+ - Reporting guidelines and citation policy: [references/reporting-shortcuts.md](references/reporting-shortcuts.md)
## Related Skills
- - `/manuscript-review-council` — run a multi-reviewer critique before revision
- - `/proposal-review` — switch here for funding-proposal critique
- - `/bio-logic` — evaluate evidence quality and rigor during revision
- - `/crossref-lookup` — validate every cited DOI
+ - `/manuscript-review-council`: multi-reviewer critique before revision
+ - `/proposal-review`: funding-proposal critique
+ - `/bio-logic`: evidence quality and rigor during revision
+ - `/crossref-lookup`: DOI validation for every cited reference