Medical Manuscript Writing

Transform manuscripts from data reports into persuasive scientific arguments.

The Core Shift

Stop reporting. Start arguing.

Report Thinking	Argumentation Thinking
"I did X, found Y, concluded Z"	"There's a problem, current answers fall short, here's a better one"
Paragraphs present data	Every paragraph advances the argument
Reader sees your lab notebook	Reader sees your insight

Before writing any paragraph, ask: What role does this play in my argument? If you can't answer, the paragraph doesn't belong — or needs repositioning.

When to Use

• Writing a new original research manuscript
• Revising a draft that reads "flat" or "boring"
• Reviewing a colleague's manuscript for structural issues
• Preparing a response to reviewer comments
• Transitioning from thesis/report style to journal style

Master Checklist

Copy and track progress through each section:

Pre-Writing

• Define your nugget: the single insight that makes your problem solvable
• Define your one-sentence argument (what gap you fill and why it matters)
• Write a 3-sentence elevator pitch (problem → insight → result)
• Identify your target journal and its conventions
• Outline the logical chain: Gap → Approach → Key Finding → Implication
• Draft placeholder figures — they are the paper's skeleton
• Identify your audience (clinicians, methodologists, policy makers?)
• Write a shitty first draft early — perfection comes in revision

Detailed guidance: references/process.md

Title

• Condenses the key insight (not just the topic)
• Searchable — contains main variables, population, and study design
• Under journal character limit
• No abbreviations (unless universally recognized like ICU, HIV)

Abstract

• Follows journal's required structured format (Background/Methods/Results/Conclusions)
• Background uses Goal → Problem → Solution rhythm
• Results state primary outcome with effect size and 95% CI
• Conclusions state the clinical implication, not just the statistical finding
• No claims absent from the main text
• Word count within journal limit

Detailed guidance: references/abstract.md

Introduction

• Opens with a specific clinical dilemma, not a textbook sentence
• Literature builds a logical chain toward your gap (not a stack of citations)
• Gap statement is crisp and specific
• Final paragraph states exact study strategy (data, method, outcome)
• Every citation serves a purpose (importance, prior limitation, or theoretical basis)

Detailed guidance: references/introduction.md

Methods

• Organized by research logic, not by tool category
• Key methodological decisions include justification ("why this method")
• Sensitivity analyses target your biggest threats to validity
• Reporting follows a guideline (STROBE, CONSORT, PRISMA, etc.)

Detailed guidance: references/methods.md

Results

• Opens with a bird's-eye view before any details
• Baseline characteristics in text limited to clinically relevant differences
• Presentation order follows research questions, not analysis chronology
• No interpretation or speculation (no "This suggests..." or "This may be because...")
• Tables and figures referenced by finding, not narrated line-by-line

Detailed guidance: references/results.md

Discussion

• First paragraph is a conceptual elevator pitch (finding + clinical picture + significance)
• Interpretation organized in layers (biological → methodological → clinical)
• Inconsistent results honestly engaged, not ignored
• Literature comparison builds your explanatory framework, not a citation list
• Limitations are balanced: acknowledge → mitigate → contextualize
• Conclusion states clinical implication, not just statistical summary

Detailed guidance: references/discussion.md

Sentence-Level Polish

• Subjects are study variables or actions, not passive constructions
• Each paragraph's first and last sentences carry the main message
• No hedge stacking ("may possibly potentially suggest...")
• Eliminated empty adjectives ("interesting", "important", "noteworthy")
• Read aloud — every sentence flows naturally

Detailed guidance: references/sentence-craft.md

Figures & Tables

• Every figure has a single take-home message
• Figure legends are self-contained (method, sample, key stats, abbreviations)
• Tables show only study-relevant variables (extras go to supplement)
• Large-sample comparisons use SMD instead of p-values where appropriate

Detailed guidance: references/figures-tables.md

Overall Rhythm

• Information-dense paragraphs followed by interpretive breathing room
• No three consecutive paragraphs with the same "found A, p=B, consistent with C" pattern
• Transitions between sections feel guided, not mechanical
• Read aloud — if it sounds dull or stilted to you, it reads worse to others

Section Quick Reference

Section	Goal	Fatal Mistake	Fix
Title	Condense key insight	Generic topic label ("A Study of X and Y")	Include variables + finding direction
Abstract	Standalone argument	Missing structured rhythm	Goal → Problem → Solution in each sub-section
Introduction	Build logical case for your study	Starting with "X is a leading cause of death"	Open with a specific clinical dilemma
Methods	Earn reader trust	Listing tools without justification	Explain why for key decisions
Results	Present facts that advance the argument	Smuggling interpretation ("suggests...")	Facts only; interpretation in Discussion
Discussion	Provide conceptual significance	Restating results with p-values	Lead with meaning, not numbers
Figures	Deliver one message per figure	Cluttered figures without clear takeaway	Design around the take-home message

Common Anti-Patterns

Anti-Pattern	Example	Better Approach
Textbook opening	"Cancer is a leading cause of death worldwide"	Specific clinical dilemma your study addresses
Citation stacking	"Smith (2020) found X. Jones (2021) found Y."	Synthesize into a logical chain with inline citations
Vague study aim	"We aimed to explore the relationship between X and Y"	"We used [database] with [method] to test [specific hypothesis]"
Lab-notebook Results	Narrating every row of Table 1	Highlight only clinically meaningful differences
Statistical Discussion	"HR was 2.4 (95% CI 1.8–3.2, p<0.001)" as Discussion opener	Lead with conceptual significance, not numbers
Self-destructive Limitations	Listing every weakness until the study sounds worthless	Acknowledge → mitigate → contextualize
Hedge stacking	"It is possible that this may potentially suggest..."	One hedge per claim: "This suggests..."
Empty adjectives	"Interestingly, we found..."	Show the contrast or surprise directly
Afterthought title	"A Study of LDH Levels in ICU Patients"	Condense the nugget: "Serial LDH Trajectories Predict 90-Day Mortality in Critically Ill Patients"
No defined nugget	Starting to write without a core argument	Define the one insight that makes your problem solvable before writing
Rough draft to senior author	Sending a messy draft expecting rescue	Polish first; let them focus on argument, not grammar

Reviewer Psychology

Reviewers must: (1) summarize your paper, (2) identify strengths, (3) evaluate validity, (4) find weaknesses. Support them:

Reviewer Need	How to Help
Summarize	Crystal-clear abstract + Discussion opener = easy summary
Identify strengths	Explicit contribution statements in Introduction's final paragraph
Evaluate validity	Sensitivity analyses with clear reporting in Results
Find weaknesses	Honest limitations section (they will find them regardless)

If a reviewer cannot quickly summarize your paper, your structure has failed — not the reviewer.

Detailed guidance: references/process.md

Proofreading Protocol

• Read for argument flow — does the logic build from Introduction through Conclusion?
• Read every word, caption, and abbreviation — detail pass
• Read as a naïve reader — where do you get confused?
• Read as a hostile reviewer — what would you attack?
• Verify all numbers in text match their corresponding tables and figures
• Have at least two co-authors proofread independently
• Assume your bibliography has errors — verify every citation

Detailed guidance: references/process.md

Quick Scan

Run the built-in scanner to catch mechanical anti-patterns (31 checks, section-aware):

# Full scan
python3 ~/.claude/skills/manuscript/scan-manuscript.py manuscript.md

# Errors only (high confidence)
python3 ~/.claude/skills/manuscript/scan-manuscript.py --severity error manuscript.md

# Check a single section from stdin
cat results.md | python3 ~/.claude/skills/manuscript/scan-manuscript.py --section Results

# JSON output / markdown checklist
python3 ~/.claude/skills/manuscript/scan-manuscript.py --json manuscript.md
python3 ~/.claude/skills/manuscript/scan-manuscript.py --checklist manuscript.md

# List all checks
python3 ~/.claude/skills/manuscript/scan-manuscript.py --list-checks

What it catches (~57% of this skill's scriptable guidance): hedge stacking, empty adjectives, interpretation in Results, textbook openings, vague aims, p-values without CIs, citation stacking (Introduction + Discussion), contractions, duplicate words, tautological acronyms (HIV virus), passive voice ratio, sentence monotony, table/figure narration, statistical Discussion openers, statistical conclusions, mechanical transitions, overclaiming, anthropomorphism, informal language, British/American spelling mix, nominalizations, wordy phrases, redundant modifiers, self-referential filler, sentence sprawl, double negatives, missing reporting guidelines, p-value ordering, monotonous results patterns.

What it cannot catch (~43%): argumentation quality, logical chains, gap specificity, interpretive framework depth, limitation balance. These require human judgment or AI-assisted review.

Related Skills

• /human-write — Scan for AI-flavored vocabulary
• /meta-manuscript-assembly — Assemble tables, figures, references for meta-analyses
• /scientific-figure-assembly — Create multi-panel publication figures
• /vale — Lint prose for style and grammar
• /strobe-check — Audit observational studies (cohort, case-control, cross-sectional) against STROBE
• /prisma-check — Audit systematic reviews and meta-analyses against PRISMA 2020
• /care-check — Audit case reports against CARE checklist
• /consort-check — Audit RCTs against CONSORT 2010
• /tripod-check — Audit prediction models and clinical AI against TRIPOD+AI