ml-paper-writing

AI-generated citations have a ~40% error rate. Hallucinated references—papers that don't exist, wrong authors, incorrect years, fabricated DOIs—are a serious form of academic misconduct that can result in desk rejection or retraction.

NEVER generate BibTeX entries from memory. ALWAYS fetch programmatically.

If you cannot programmatically verify a citation, you MUST:

% EXPLICIT PLACEHOLDER - requires human verification
\cite{PLACEHOLDER_author2024_verify_this}  % TODO: Verify this citation exists

Always tell the scientist: "I've marked [X] citations as placeholders that need verification. I could not confirm these papers exist."

For the best paper search experience, install Exa MCP which provides real-time academic search:

Claude Code:

claude mcp add exa -- npx -y mcp-remote "https://mcp.exa.ai/mcp"

Cursor / VS Code (add to MCP settings):

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

Exa MCP enables searches like:

• "Find papers on RLHF for language models published after 2023"
• "Search for transformer architecture papers by Vaswani"
• "Get recent work on sparse autoencoders for interpretability"

Then verify results with Semantic Scholar API and fetch BibTeX via DOI.

Copy this checklist and track progress. Each step involves drafting → feedback → revision:

Paper Writing Progress:
- [ ] Step 1: Define the one-sentence contribution (with scientist)
- [ ] Step 2: Draft Figure 1 → get feedback → revise
- [ ] Step 3: Draft abstract → get feedback → revise
- [ ] Step 4: Draft introduction → get feedback → revise
- [ ] Step 5: Draft methods → get feedback → revise
- [ ] Step 6: Draft experiments → get feedback → revise
- [ ] Step 7: Draft related work → get feedback → revise
- [ ] Step 8: Draft limitations → get feedback → revise
- [ ] Step 9: Complete paper checklist (required)
- [ ] Step 10: Final review cycle and submission

Step 1: Define the One-Sentence Contribution

This step requires explicit confirmation from the scientist.

Before writing anything, articulate and verify:

• What is the single thing your paper contributes?
• What was not obvious or present before your work?

"I propose framing the contribution as: '[one sentence]'. Does this capture what you see as the main takeaway? Should we adjust the emphasis?"

Step 2: Draft Figure 1

Figure 1 deserves special attention—many readers skip directly to it.

• Convey core idea, approach, or most compelling result
• Use vector graphics (PDF/EPS for plots)
• Write captions that stand alone without main text
• Ensure readability in black-and-white (8% of men have color vision deficiency)

Step 3: Write Abstract (5-Sentence Formula)

From Sebastian Farquhar (DeepMind):

1. What you achieved: "We introduce...", "We prove...", "We demonstrate..."
2. Why this is hard and important
3. How you do it (with specialist keywords for discoverability)
4. What evidence you have
5. Your most remarkable number/result

Delete generic openings like "Large language models have achieved remarkable success..."

Step 4: Write Introduction (1-1.5 pages max)

Must include:

• 2-4 bullet contribution list (max 1-2 lines each in two-column format)
• Clear problem statement
• Brief approach overview
• Methods should start by page 2-3 maximum

Step 5: Methods Section

Enable reimplementation:

• Conceptual outline or pseudocode
• All hyperparameters listed
• Architectural details sufficient for reproduction
• Present final design decisions; ablations go in experiments

Step 6: Experiments Section

For each experiment, explicitly state:

• What claim it supports
• How it connects to main contribution
• Experimental setting (details in appendix)
• What to observe: "the blue line shows X, which demonstrates Y"

Requirements:

• Error bars with methodology (standard deviation vs standard error)
• Hyperparameter search ranges
• Compute infrastructure (GPU type, total hours)
• Seed-setting methods

Step 7: Related Work

Organize methodologically, not paper-by-paper:

Good: "One line of work uses Floogledoodle's assumption [refs] whereas we use Doobersnoddle's assumption because..."

Bad: "Snap et al. introduced X while Crackle et al. introduced Y."

Cite generously—reviewers likely authored relevant papers.

Step 8: Limitations Section (REQUIRED)

All major conferences require this. Counter-intuitively, honesty helps:

• Reviewers are instructed not to penalize honest limitation acknowledgment
• Pre-empt criticisms by identifying weaknesses first
• Explain why limitations don't undermine core claims

Step 9: Paper Checklist

NeurIPS, ICML, and ICLR all require paper checklists. See references/checklists.md.

This skill synthesizes writing philosophy from researchers who have published extensively at top venues:

For deeper dives into any of these, see:

• references/writing-guide.md - Full explanations with examples
• references/sources.md - Complete bibliography

Spend approximately equal time on each of:

1. The abstract
2. The introduction
3. The figures
4. Everything else combined

Why? Most reviewers form judgments before reaching your methods. Readers encounter your paper as: title → abstract → introduction → figures → maybe the rest.

These principles are based on how readers actually process prose. Violating them forces readers to spend cognitive effort on structure rather than content.

Full 7 principles with detailed examples: See references/writing-guide.md

These small changes accumulate into significantly clearer prose:

• Minimize pronouns: ❌ "This shows..." → ✅ "This result shows..."
• Verbs early: Position verbs near sentence start
• Unfold apostrophes: ❌ "X's Y" → ✅ "The Y of X" (when awkward)
• Delete filler words: "actually," "a bit," "very," "really," "basically," "quite," "essentially"

Full micro-tips with examples: See references/writing-guide.md

• Be specific: ❌ "performance" → ✅ "accuracy" or "latency" (say what you mean)
• Eliminate hedging: Drop "may" and "can" unless genuinely uncertain
• Avoid incremental vocabulary: ❌ "combine," "modify," "expand" → ✅ "develop," "propose," "introduce"
• Delete intensifiers: ❌ "provides very tight approximation" → ✅ "provides tight approximation"

• Consistent terminology: Different terms for same concept creates confusion. Pick one and stick with it.
• State assumptions formally: Before theorems, list all assumptions explicitly
• Intuition + rigor: Provide intuitive explanations alongside formal proofs

Understanding reviewer behavior helps prioritize your effort:

Bottom line: If your abstract and intro don't hook reviewers, they may never read your brilliant methods section.

Systems Conferences (OSDI, NSDI, ASPLOS, SOSP): See the systems-paper-writing skill for page limits, templates, deadlines, and submission rules.

Universal Requirements:

• Double-blind review (anonymize submissions)
• References don't count toward page limit
• Appendices unlimited but reviewers not required to read
• LaTeX required for all venues

LaTeX Templates: See templates/ directory for all conference templates.

Always copy the entire template directory first, then write within it.

Template Setup Checklist:
- [ ] Step 1: Copy entire template directory to new project
- [ ] Step 2: Verify template compiles as-is (before any changes)
- [ ] Step 3: Read the template's example content to understand structure
- [ ] Step 4: Replace example content section by section
- [ ] Step 5: Keep template comments/examples as reference until done
- [ ] Step 6: Clean up template artifacts only at the end

Step 1: Copy the Full Template

# Create your paper directory with the complete template
cp -r templates/neurips2025/ ~/papers/my-new-paper/
cd ~/papers/my-new-paper/

# Verify structure is complete
ls -la
# Should see: main.tex, neurips.sty, Makefile, etc.

⚠️ IMPORTANT: Copy the ENTIRE directory, not just main.tex. Templates include:

• Style files (.sty) - required for compilation
• Bibliography styles (.bst) - required for references
• Example content - useful as reference
• Makefiles - for easy compilation

Step 2: Verify Template Compiles First

Before making ANY changes, compile the template as-is:

# Using latexmk (recommended)
latexmk -pdf main.tex

# Or manual compilation
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex

If the unmodified template doesn't compile, fix that first. Common issues:

• Missing TeX packages → install via tlmgr install <package>
• Wrong TeX distribution → use TeX Live (recommended)

Step 3: Keep Template Content as Reference

Don't immediately delete all example content. Instead:

% KEEP template examples commented out as you write
% This shows you the expected format

% Template example (keep for reference):
% \begin{figure}[t]
%   \centering
%   \includegraphics[width=0.8\linewidth]{example-image}
%   \caption{Template shows caption style}
% \end{figure}

% Your actual figure:
\begin{figure}[t]
  \centering
  \includegraphics[width=0.8\linewidth]{your-figure.pdf}
  \caption{Your caption following the same style.}
\end{figure}

Step 4: Replace Content Section by Section

Work through the paper systematically:

Replacement Order:
1. Title and authors (anonymize for submission)
2. Abstract
3. Introduction
4. Methods
5. Experiments
6. Related Work
7. Conclusion
8. References (your .bib file)
9. Appendix

For each section:

1. Read the template's example content
2. Note any special formatting or macros used
3. Replace with your content following the same patterns
4. Compile frequently to catch errors early

Step 5: Use Template Macros

Templates often define useful macros. Check the preamble for:

% Common template macros to use:
\newcommand{\method}{YourMethodName}  % Consistent method naming
\newcommand{\eg}{e.g.,\xspace}        % Proper abbreviations
\newcommand{\ie}{i.e.,\xspace}
\newcommand{\etal}{\textit{et al.}\xspace}

Step 6: Clean Up Only at the End

Only remove template artifacts when paper is nearly complete:

% BEFORE SUBMISSION - remove these:
% - Commented-out template examples
% - Unused packages
% - Template's example figures/tables
% - Lorem ipsum or placeholder text

% KEEP these:
% - All style files (.sty)
% - Bibliography style (.bst)
% - Required packages from template
% - Any custom macros you're using

Systems Conference Templates (OSDI, NSDI, ASPLOS, SOSP): See the systems-paper-writing skill.

Format Conversion Checklist:
- [ ] Step 1: Identify source and target template differences
- [ ] Step 2: Create new project with target template
- [ ] Step 3: Copy content sections (not preamble)
- [ ] Step 4: Adjust page limits and content
- [ ] Step 5: Update conference-specific requirements
- [ ] Step 6: Verify compilation and formatting

Step 1: Key Template Differences

ML → Systems Conversion: When converting to OSDI, NSDI, ASPLOS, or SOSP, see the systems-paper-writing skill for format conversion guidance, templates, and structural differences.

Step 2: Content Migration (NOT Template Merge)

Never copy LaTeX preambles between templates. Instead:

# 1. Start fresh with target template
cp -r templates/icml2026/ new_submission/

# 2. Copy ONLY content sections from old paper
# - Abstract text
# - Section content (between \section{} commands)
# - Figures and tables
# - Bibliography entries

# 3. Paste into target template structure

Step 3: Adjusting for Page Limits

When cutting pages (e.g., NeurIPS 9 → AAAI 7):

• Move detailed proofs to appendix
• Condense related work (cite surveys instead of individual papers)
• Combine similar experiments into unified tables
• Use smaller figure sizes with subfigures
• Tighten writing: eliminate redundancy, use active voice

When expanding (e.g., ICML 8 → ICLR 9):

• Add ablation studies reviewers requested
• Expand limitations discussion
• Include additional baselines
• Add qualitative examples

Step 4: Conference-Specific Adjustments

Systems Venues (OSDI, NSDI, ASPLOS, SOSP): See the systems-paper-writing skill for venue-specific requirements, checklists, and reviewer guidelines.

Step 5: Update References

% Remove self-citations that reveal identity (for blind review)
% Update any "under review" citations to published versions
% Add new relevant work published since last submission

Step 6: Addressing Previous Reviews

When resubmitting after rejection:

• Do address reviewer concerns in the new version
• Do add experiments/clarifications reviewers requested
• Don't include a "changes from previous submission" section (blind review)
• Don't reference the previous submission or reviews

Common Conversion Pitfalls:

• ❌ Copying \usepackage commands (causes conflicts)
• ❌ Keeping old conference header/footer commands
• ❌ Forgetting to update \bibliography{} path
• ❌ Missing conference-specific required sections
• ❌ Exceeding page limit after format change

Citation Verification (MANDATORY for every citation):
- [ ] Step 1: Search using Exa MCP or Semantic Scholar API
- [ ] Step 2: Verify paper exists in 2+ sources (Semantic Scholar + arXiv/CrossRef)
- [ ] Step 3: Retrieve BibTeX via DOI (programmatically, not from memory)
- [ ] Step 4: Verify the claim you're citing actually appears in the paper
- [ ] Step 5: Add verified BibTeX to bibliography
- [ ] Step 6: If ANY step fails → mark as placeholder, inform scientist

Step 0: Use Exa MCP for Initial Search (Recommended)

If Exa MCP is installed, use it to find relevant papers:

Search: "RLHF language model alignment 2023"
Search: "sparse autoencoders interpretability"
Search: "attention mechanism transformers Vaswani"

Then verify each result with Semantic Scholar and fetch BibTeX via DOI.

Step 1: Search Semantic Scholar

from semanticscholar import SemanticScholar

sch = SemanticScholar()
results = sch.search_paper("attention mechanism transformers", limit=5)
for paper in results:
    print(f"{paper.title} - {paper.paperId}")
    print(f"  DOI: {paper.externalIds.get('DOI', 'N/A')}")

Step 2: Verify Existence

Confirm paper appears in at least two sources (Semantic Scholar + CrossRef/arXiv).

Step 3: Retrieve BibTeX via DOI

import requests

def doi_to_bibtex(doi: str) -> str:
    """Get verified BibTeX from DOI via CrossRef."""
    response = requests.get(
        f"https://doi.org/{doi}",
        headers={"Accept": "application/x-bibtex"}
    )
    response.raise_for_status()
    return response.text

# Example
bibtex = doi_to_bibtex("10.48550/arXiv.1706.03762")
print(bibtex)

Step 4: Verify Claims

Before citing for a specific claim, access the paper and confirm the attributed claim actually appears.

Step 5: Handle Failures Explicitly

If you cannot verify a citation at ANY step:

% Option 1: Explicit placeholder
\cite{PLACEHOLDER_smith2023_verify}  % TODO: Could not verify - scientist must confirm

% Option 2: Note in text
... as shown in prior work [CITATION NEEDED - could not verify Smith et al. 2023].

Always inform the scientist:

"I could not verify the following citations and have marked them as placeholders:

• Smith et al. 2023 on reward hacking - could not find in Semantic Scholar
• Jones 2022 on scaling laws - found similar paper but different authors Please verify these before submission."

🚨 NEVER generate BibTeX from memory—always fetch programmatically. 🚨

See references/citation-workflow.md for complete API documentation.

Use booktabs LaTeX package for professional tables:

\usepackage{booktabs}
\begin{tabular}{lcc}
\toprule
Method & Accuracy ↑ & Latency ↓ \\
\midrule
Baseline & 85.2 & 45ms \\
\textbf{Ours} & \textbf{92.1} & 38ms \\
\bottomrule
\end{tabular}

Rules:

• Bold best value per metric
• Include direction symbols (↑ higher is better, ↓ lower is better)
• Right-align numerical columns
• Consistent decimal precision

• Vector graphics (PDF, EPS) for all plots and diagrams
• Raster (PNG 600 DPI) only for photographs
• Use colorblind-safe palettes (Okabe-Ito or Paul Tol)
• Verify grayscale readability (8% of men have color vision deficiency)
• No title inside figure—the caption serves this function
• Self-contained captions—reader should understand without main text

Templates in templates/ directory:

• ML/AI: ICML 2026, ICLR 2026, NeurIPS 2025, ACL/EMNLP, AAAI 2026, COLM 2025
• Systems (OSDI, NSDI, ASPLOS, SOSP): See systems-paper-writing skill

Compiling to PDF:

• VS Code/Cursor: Install LaTeX Workshop extension + TeX Live → Save to auto-compile
• Command line: latexmk -pdf main.tex or pdflatex + bibtex workflow
• Online: Upload to Overleaf

See templates/README.md for detailed setup instructions.

Writing Philosophy:

• Neel Nanda: How to Write ML Papers - Narrative, "What/Why/So What"
• Farquhar: How to Write ML Papers - 5-sentence abstract
• Gopen & Swan: Science of Scientific Writing - 7 reader expectation principles
• Lipton: Heuristics for Scientific Writing - Word choice
• Perez: Easy Paper Writing Tips - Micro-level clarity

APIs: Semantic Scholar | CrossRef | arXiv

ML/AI Venues: NeurIPS | ICML | ICLR | ACL

Systems Venues: See the systems-paper-writing skill for OSDI, NSDI, ASPLOS, SOSP links and guides