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-checksWhat 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