Scientific Writing

Scientific Writing

Overview

This is the core journal-writing skill in this repository. Use it to turn a stable scientific story into clear, well-structured manuscript prose while keeping citations, figures, and reporting standards aligned.

Scientific writing is a process for communicating research with precision and clarity. Write manuscripts using IMRAD structure, citations (APA/AMA/Vancouver), figures/tables, and reporting guidelines (CONSORT/STROBE/PRISMA). Apply this skill for research papers and journal submissions.

Critical Principle: Always write in full paragraphs with flowing prose. Never submit bullet points in the final manuscript. Use a two-stage process: first create section outlines with key points from verified notes, literature, and results, then convert those outlines into complete paragraphs.

For revision-heavy journal manuscripts, do not jump from stale prose directly to polishing. First stabilize the section with a reverse outline and a claim-evidence map, then rewrite the paragraphs.

When to Use This Skill

This skill should be used when:

• Writing or revising any section of a scientific manuscript (abstract, introduction, methods, results, discussion)
• Structuring a research paper using IMRAD or other standard formats
• Formatting citations and references in specific styles (APA, AMA, Vancouver, Chicago, IEEE)
• Creating, formatting, or improving figures, tables, and data visualizations
• Applying study-specific reporting guidelines (CONSORT for trials, STROBE for observational studies, PRISMA for reviews)
• Drafting abstracts that meet journal requirements (structured or unstructured)
• Preparing manuscripts for submission to specific journals
• Improving writing clarity, conciseness, and precision
• Ensuring proper use of field-specific terminology and nomenclature
• Addressing reviewer comments and revising manuscripts

For title, abstract, cover-letter, or top-level logic decisions, read references/editor-first-impression.md.

Visual Enhancement with Scientific Figures

When a manuscript would benefit from a schematic, workflow diagram, or conceptual figure, use this repository's nature-figure skill, which ships an OpenRouter AI-schematic route. It is not in the default recommended set because it needs a plotting backend or an OPENROUTER_API_KEY; install it from the Figure Stack (see the installation docs).

Before finalizing any document:

1. Add at least one figure when it materially improves comprehension.
2. Prefer 2-3 figures for longer papers (methods flowchart, results visualization, conceptual diagram).

How to generate figures:

• Use the nature-figure skill's OpenRouter route to generate publication-style schematics.
• Write prompts that specify academic style, white background, clean labels, colorblind-friendly colors, and high contrast.
• Save outputs under a local figures/ directory in the current project.

Example command (via the nature-figure skill, once installed):

export OPENROUTER_API_KEY="sk-or-..."
python ~/.codex/skills/nature-figure/scripts/generate_openrouter_schematic.py \
  --title "Your method" \
  --panel-map "left: problem; center: proposed mechanism; right: validated outcome" \
  --outdir figures --basename schematic --resolution 2K
# Claude Code (global install): replace ~/.codex/skills with ~/.claude/skills
# Claude Code (project-local install): replace ~/.codex/skills with .claude/skills

Requires OPENROUTER_API_KEY. Iterate on the panel map and title until the figure is publication-ready. See nature-figure's references/openrouter-image-generation.md for full options.

When to add figures:

• Study design and methodology flowcharts (CONSORT, PRISMA, STROBE)
• Conceptual framework diagrams
• Experimental workflow illustrations
• Data analysis pipeline diagrams
• Biological pathway or mechanism diagrams
• System architecture visualizations
• Any complex concept that benefits from visualization

For detailed guidance on creating figures, refer to the nature-figure skill.

Core Capabilities

1. Manuscript Structure and Organization

IMRAD Format: Guide papers through the standard Introduction, Methods, Results, And Discussion structure used across most scientific disciplines. This includes:

• Introduction: Establish research context, identify gaps, state objectives
• Methods: Detail study design, populations, procedures, and analysis approaches
• Results: Present findings objectively without interpretation
• Discussion: Interpret results, acknowledge limitations, propose future directions

For detailed guidance on IMRAD structure, refer to references/imrad_structure.md.

Alternative Structures: Support discipline-specific formats including:

• Review articles (narrative, systematic, scoping)
• Case reports and case series
• Meta-analyses and pooled analyses
• Theoretical/modeling papers
• Methods papers and protocols

2. Section-Specific Writing Guidance

Editor-First Front Door: Make the title, abstract, introduction, Results, discussion, and cover letter answer the same four questions in the same order:

• why did the study need to be done
• what did you do
• what did you find
• how does the study advance the field

If these sections answer different versions of the story, the manuscript will feel fragmented even when the prose is locally strong.

Abstract Composition: Craft concise, standalone summaries (100-250 words) that capture the paper's purpose, methods, results, and conclusions. Support both structured abstracts (with labeled sections) and unstructured single-paragraph formats. Make the abstract state the problem, the aim/method, the key result, and the implication. Do not spend most of the space on generic background or report only that results were significant.

Title and Cover Letter: Make the title a concise summary of the main contribution, ideally about 20 words or fewer. Prefer concrete keywords, avoid question-form titles, avoid unnecessary abbreviations, and avoid making the method the title unless the method itself is the main contribution. Make the cover letter about one page, state significance, journal fit, readership fit, and one or two key findings, and do not turn it into a second abstract or a full result list.

Top-Level Logic: Keep one visible chain across the manuscript:

• topic
• published work
• unresolved problem
• objective
• methodology
• results and figures
• summary of findings
• interpretation
• implication for the field

Introduction Development: Build compelling introductions that:

• Establish the research problem's importance
• Review relevant literature systematically
• Identify knowledge gaps or controversies
• State clear research questions or hypotheses
• Explain the study's novelty and significance

Methods Documentation: Ensure reproducibility through:

• Detailed participant/sample descriptions
• Clear procedural documentation
• Statistical methods with justification
• Equipment and materials specifications
• Ethical approval and consent statements

Results Presentation: Present findings with:

• Logical flow from primary to secondary outcomes
• Integration with figures and tables
• Statistical significance with effect sizes
• Objective reporting without interpretation

Discussion Construction: Synthesize findings by:

• Relating results to research questions
• Comparing with existing literature
• Acknowledging limitations honestly
• Proposing mechanistic explanations
• Suggesting practical implications and future research

3. Citation and Reference Management

Apply citation styles correctly across disciplines. For comprehensive style guides, refer to references/citation_styles.md.

Major Citation Styles:

• AMA (American Medical Association): Numbered superscript citations, common in medicine
• Vancouver: Numbered citations in square brackets, biomedical standard
• APA (American Psychological Association): Author-date in-text citations, common in social sciences
• Chicago: Notes-bibliography or author-date, humanities and sciences
• IEEE: Numbered square brackets, engineering and computer science

Best Practices:

• Cite primary sources when possible
• Include recent literature (last 5-10 years for active fields)
• Balance citation distribution across introduction and discussion
• Verify all citations against original sources
• Use reference management software (Zotero, Mendeley, EndNote)

4. Figures and Tables

Create effective data visualizations that enhance comprehension. For detailed best practices, refer to references/figures_tables.md.

When to Use Tables vs. Figures:

• Tables: Precise numerical data, complex datasets, multiple variables requiring exact values
• Figures: Trends, patterns, relationships, comparisons best understood visually

Design Principles:

• Make each table/figure self-explanatory with complete captions
• Use consistent formatting and terminology across all display items
• Label all axes, columns, and rows with units
• Include sample sizes (n) and statistical annotations
• Follow the "one table/figure per 1000 words" guideline
• Avoid duplicating information between text, tables, and figures

Common Figure Types:

• Bar graphs: Comparing discrete categories
• Line graphs: Showing trends over time
• Scatterplots: Displaying correlations
• Box plots: Showing distributions and outliers
• Heatmaps: Visualizing matrices and patterns

5. Reporting Guidelines by Study Type

Ensure completeness and transparency by following established reporting standards. For comprehensive guideline details, refer to references/reporting_guidelines.md.

Key Guidelines:

• CONSORT: Randomized controlled trials
• STROBE: Observational studies (cohort, case-control, cross-sectional)
• PRISMA: Systematic reviews and meta-analyses
• STARD: Diagnostic accuracy studies
• TRIPOD: Prediction model studies
• ARRIVE: Animal research
• CARE: Case reports
• SQUIRE: Quality improvement studies
• SPIRIT: Study protocols for clinical trials
• CHEERS: Economic evaluations

Each guideline provides checklists ensuring all critical methodological elements are reported.

6. Writing Principles and Style

Apply fundamental scientific writing principles. For detailed guidance, refer to references/writing_principles.md.

Clarity:

• Use precise, unambiguous language
• Define technical terms and abbreviations at first use
• Maintain logical flow within and between paragraphs
• Use active voice when appropriate for clarity

Conciseness:

• Eliminate redundant words and phrases
• Favor shorter sentences (15-20 words average)
• Remove unnecessary qualifiers
• Respect word limits strictly

Accuracy:

• Report exact values with appropriate precision
• Use consistent terminology throughout
• Distinguish between observations and interpretations
• Acknowledge uncertainty appropriately

Objectivity:

• Present results without bias
• Avoid overstating findings or implications
• Acknowledge conflicting evidence
• Maintain professional, neutral tone

7. Writing Process: From Outline to Full Paragraphs

CRITICAL: Always write in full paragraphs, never submit bullet points in scientific papers.

Scientific papers must be written in complete, flowing prose. Use this two-stage approach for effective writing:

Stage 1: Create Section Outlines with Key Points

When starting a new section:

1. Gather the relevant literature and data from verified local notes, trusted web sources, or an installed literature-search skill
2. Create a structured outline with bullet points marking:
   • Main arguments or findings to present
   • Key studies to cite
   • Data points and statistics to include
   • Logical flow and organization
3. These bullet points serve as scaffolding—they are NOT the final manuscript

Example outline (Introduction section):

- Background: AI in drug discovery gaining traction
  * Cite recent reviews (Smith 2023, Jones 2024)
  * Traditional methods are slow and expensive
- Gap: Limited application to rare diseases
  * Only 2 prior studies (Lee 2022, Chen 2023)
  * Small datasets remain a challenge
- Our approach: Transfer learning from common diseases
  * Novel architecture combining X and Y
- Study objectives: Validate on 3 rare disease datasets

Stage 2: Convert Key Points to Full Paragraphs

Once the outline is complete, expand each bullet point into proper prose:

1. Transform bullet points into complete sentences with subjects, verbs, and objects
2. Add transitions between sentences and ideas (however, moreover, in contrast, subsequently)
3. Integrate citations naturally within sentences, not as lists
4. Expand with context and explanation that bullet points omit
5. Ensure logical flow from one sentence to the next within each paragraph
6. Vary sentence structure to maintain reader engagement

Example conversion to prose:

Artificial intelligence approaches have gained significant traction in drug discovery 
pipelines over the past decade (Smith, 2023; Jones, 2024). While these computational 
methods show promise for accelerating the identification of therapeutic candidates, 
traditional experimental approaches remain slow and resource-intensive, often requiring 
years of laboratory work and substantial financial investment. However, the application 
of AI to rare diseases has been limited, with only two prior studies demonstrating 
proof-of-concept results (Lee, 2022; Chen, 2023). The primary obstacle has been the 
scarcity of training data for conditions affecting small patient populations. 

To address this challenge, we developed a transfer learning approach that leverages 
knowledge from well-characterized common diseases to predict therapeutic targets for 
rare conditions. Our novel neural architecture combines convolutional layers for 
molecular feature extraction with attention mechanisms for protein-ligand interaction 
modeling. The objective of this study was to validate our approach across three 
independent rare disease datasets, assessing both predictive accuracy and biological 
interpretability of the results.

Key Differences Between Outlines and Final Text:

Common Mistakes to Avoid:

• ❌ Never leave bullet points in the final manuscript
• ❌ Never submit lists where paragraphs should be
• ❌ Don't use numbered or bulleted lists in Results or Discussion sections (except for specific cases like study hypotheses or inclusion criteria)
• ❌ Don't write sentence fragments or incomplete thoughts
• ✅ Do use occasional lists only in Methods (e.g., inclusion/exclusion criteria, materials lists)
• ✅ Do ensure every section flows as connected prose
• ✅ Do read paragraphs aloud to check for natural flow

When Lists ARE Acceptable (Limited Cases):

Lists may appear in scientific papers only in specific contexts:

• Methods: Inclusion/exclusion criteria, materials and reagents, participant characteristics
• Supplementary Materials: Extended protocols, equipment lists, detailed parameters
• Never in: Abstract, Introduction, Results, Discussion, Conclusions

Integration with Literature Search:

Verified literature gathering is essential for Stage 1 (creating outlines):

1. Search for relevant papers using trusted sources or an installed literature-search skill
2. Extract key findings, methods, and data
3. Organize findings as bullet points in your outline
4. Then convert the outline to full paragraphs in Stage 2

This two-stage process ensures you:

• Gather and organize information systematically
• Create logical structure before writing
• Produce polished, publication-ready prose
• Maintain focus on the narrative flow

7A. Reverse Outline And Claim-Evidence Pass For Revisions

When revising an existing manuscript section rather than drafting from scratch:

1. Reverse-outline the current text:
   • section thesis
   • one-line message for each paragraph
   • the evidence, citation, or reasoning each paragraph carries
2. For all major claims in the Abstract, Introduction, Results topic sentences, and Discussion, write:
   • Claim: ... | Evidence: ... | Status: supported / partial / missing
3. If a claim is marked partial or missing, do one of three things only:
   • weaken it
   • add the missing evidence
   • move it into motivation, interpretation, or future work
4. Only after this pass, rewrite into full journal prose.

Use this especially when:

• the section has been revised many times
• the front half may now be stronger than the Results
• paragraph flow feels smooth but the logic still feels unstable

7B. Skeptical Self-Review Before Finalizing

Before treating a section as finished, ask:

• Is the contribution actually clear?
• Is every major claim readable and self-contained?
• Does the empirical evidence directly support the claim I am making?
• Is an important baseline, ablation, or caveat missing?
• Would a skeptical reviewer call the method, framework, or resource insufficiently justified?

If the answer is not clearly defensible from the manuscript itself, revise the section before polishing style.

8. Journal-Specific Formatting

Adapt manuscripts to journal requirements:

• Follow author guidelines for structure, length, and format
• Apply journal-specific citation styles
• Meet figure/table specifications (resolution, file formats, dimensions)
• Include required statements (funding, conflicts of interest, data availability, ethical approval)
• Adhere to word limits for each section
• Format according to template requirements when provided