scientific-writing

# Scientific Writing ## Overview **This is the core skill for the deep research and writing tool**—combining AI-driven deep research with well-formatted written outputs. Every document produced is backed by comprehensive literature search and verified citations through the research-lookup skill. 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 using research-lookup, then convert those outlines into complete 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 ## Visual Enhancement with Scientific Schematics **⚠️ MANDATORY: Every scientific paper MUST include a graphical abstract plus 1-2 additional AI-generated figures using the scientific-schematics skill.** This is not optional. Scientific papers without visual elements are incomplete. Before finalizing any document: 1. **ALWAYS generate a graphical abstract** as the first visual element 2. Generate at minimum ONE additional schematic or diagram using scientific-schematics 3. Prefer 3-4 total figures for comprehensive papers (graphical abstract + methods flowchart + results visualization + conceptual diagram) ### Graphical Abstract (REQUIRED) **Every scientific writeup MUST include a graphical abstract.** This is a visual summary of your paper that: - Appears before or immediately after the text abstract - Captures the entire paper's key message in one image - Is suitable for journal table of contents display - Uses landscape orientation (typically 1200x600px) **Generate the graphical abstract FIRST:** ```bash python scripts/generate_schematic.py "Graphical abstract for [paper title]: [brief description showing workflow from input → methods → key findings → conclusions]" -o figures/graphical_abstract.png ``` **Graphical Abstract Requirements:** - **Content**: Visual summary showing workflow, key methods, main findings, and conclusions - **Style**: Clean, professional, suitable for journal TOC - **Elements**: Include 3-5 key steps/concepts with connecting arrows or flow - **Text**: Minimal labels, large readable fonts - Log: `[HH:MM:SS] GENERATED: Graphical abstract for paper summary` ### Additional Figures (GENERATE EXTENSIVELY) **⚠️ CRITICAL: Use BOTH scientific-schematics AND generate-image EXTENSIVELY throughout all documents.** Every document should be richly illustrated. Generate figures liberally - when in doubt, add a visual. **MINIMUM Figure Requirements:** | Document Type | Minimum | Recommended | |--------------|---------|-------------| | Research Papers | 5 | 6-8 | | Literature Reviews | 4 | 5-7 | | Market Research | 20 | 25-30 | | Presentations | 1/slide | 1-2/slide | | Posters | 6 | 8-10 | | Grants | 4 | 5-7 | | Clinical Reports | 3 | 4-6 | **Use scientific-schematics EXTENSIVELY for technical diagrams:** ```bash python scripts/generate_schematic.py "your diagram description" -o figures/output.png ``` - 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 - Neural network architectures - Decision trees, algorithm flowcharts - Comparison matrices, timeline diagrams - Any technical concept that benefits from schematic visualization **Use generate-image EXTENSIVELY for visual content:** ```bash python scripts/generate_image.py "your image description" -o figures/output.png ``` - Photorealistic illustrations of concepts - Medical/anatomical illustrations - Environmental/ecological scenes - Equipment and lab setup visualizations - Artistic visualizations, infographics - Cover images, header graphics - Product mockups, prototype visualizations - Any visual that enhances understanding or engagement The AI will automatically: - Create publication-quality images with proper formatting - Review and refine through multiple iterations - Ensure accessibility (colorblind-friendly, high contrast) - Save outputs in the figures/ directory **When in Doubt, Generate a Figure:** - Complex concept → generate a schematic - Data discussion → generate a visualization - Process description → generate a flowchart - Comparison → generate a comparison diagram - Reader benefit → generate a visual For detailed guidance, refer to the scientific-schematics and generate-image skill documentation. --- ## 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 **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. **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. Use the research-lookup skill to gather relevant literature and data 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:** | Outline (Planning Stage) | Final Manuscript | |--------------------------|------------------| | Bullet points and fragments | Complete sentences and paragraphs | | Telegraphic notes | Full explanations with context | | List of citations | Citations integrated into prose | | Abbreviated ideas | Developed arguments with transitions | | For your eyes only | For publication and peer review | **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 **Abstract Format Rule:** - ❌ **NEVER** use labeled sections (Background:, Methods:, Results:, Conclusions:) - ✅ **ALWAYS** write as flowing paragraph(s) with natural transitions - Exception: Only use structured format if journal explicitly requires it in author guidelines **Integration with Research Lookup:** The research-lookup skill is essential for Stage 1 (creating outlines): 1. Search for relevant papers using research-lookup 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 ### 8. Professional Report Formatting (Non-Journal Documents) For research reports, technical reports, white papers, and other professional documents that are NOT journal manuscripts, use the `scientific_report.sty` LaTeX style package for a polished, professional appearance. **When to Use Professional Report Formatting:** - Research reports and technical reports - White papers and policy briefs - Grant reports and progress reports - Industry reports and technical documentation - Internal research summaries - Feasibility studies and project deliverables **When NOT to Use (Use Venue-Specific Formatting Instead):** - Journal manuscripts → Use `venue-templates` skill - Conference papers → Use `venue-templates` skill - Academic theses → Use institutional templates **The `scientific_report.sty` Style Package Provides:** | Feature | Description | |---------|-------------| | Typography | Helvetica font family for modern, professional appearance | | Color Scheme | Professional blues, greens, and accent colors | | Box Environments | Colored boxes for key findings, methods, recommendations, limitations | | Tables | Alternating row colors, professional headers | | Figures | Consistent caption formatting | | Scientific Commands | Shortcuts for p-values, effect sizes, confidence intervals | **Box Environments for Content Organization:** ```latex % Key findings (blue) - for major discoveries \begin{keyfindings}[Title] Content with key findings and statistics. \end{keyfindings} % Methodology (green) - for methods highlights \begin{methodology}[Study Design] Description of methods and procedures. \end{methodology} % Recommendations (purple) - for action items \begin{recommendations}[Clinical Implications] \begin{enumerate} \item Specific recommendation 1 \item Specific recommendation 2 \end{enumerate} \end{recommendations} % Limitations (orange) - for caveats and cautions \begin{limitations}[Study Limitations] Description of limitations and their implications. \end{limitations} ``` **Professional Table Formatting:** ```latex \begin{table}[htbp] \centering \caption{Results Summary} \begin{tabular}{@{}lccc@{}} \toprule \textbf{Variable} & \textbf{Treatment} & \textbf{Control} & \textbf{p} \\ \midrule Outcome 1 & \meansd{42.5}{8.3} & \meansd{35.2}{7.9} & <.001\sigthree \\ \rowcolor{tablealt} Outcome 2 & \meansd{3.8}{1.2} & \meansd{3.1}{1.1} & .012\sigone \\ Outcome 3 & \meansd{18.2}{4.5} & \meansd{17.8}{4.2} & .58\signs \\ \bottomrule \end{tabular} {\small \siglegend} \end{table} ``` **Scientific Notation Commands:** | Command | Output | Purpose | |---------|--------|---------| | `\pvalue{0.023}` | *p* = 0.023 | P-values |