Medical Manuscript Writing

Transform manuscripts from data reports into persuasive scientific arguments.

The Core Shift

Stop reporting. Start arguing.

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 one-sentence argument (what gap you fill and why it matters)
• Identify your target journal and its conventions
• Outline the logical chain: Gap → Approach → Key Finding → Implication

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

Common Anti-Patterns

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