Refining Ml Papers

Refining ML Papers: From Feedback to Camera-Ready

This skill captures battle-tested patterns for revising scientific LaTeX papers in response to reviewer/advisor feedback. Built from extensive revision work on multi-file ICML-style papers with Overleaf git workflows.

When to Use This Skill

Invoke when the user:

• Has reviewer or advisor feedback to address
• Wants to restructure paper sections (move content, merge sections)
• Needs to explain tables or figures with concrete examples
• Asks to improve exposition clarity or reduce redundancy
• Wants to fix LaTeX compilation issues after restructuring
• Needs to prepare a camera-ready or arXiv version

Core Methodology

Phase 1: Understand the Paper Architecture

Before making ANY changes:

1. Map the file structure: Glob for **/*.tex to find all LaTeX files
2. Identify the main file and all \input{} dependencies
3. Read the target sections completely before editing
4. Check for shared macros: Look for \providecommand / \newcommand patterns that indicate cross-file dependencies
5. Note existing labels: Grep for \label{ and \ref{ to understand cross-reference graph

# Typical modular structure:
main_arxiv.tex          # Preamble + abstract + introduction + \input{} calls
methods.tex             # Section 3
experiments.tex         # Section 4
appendix.tex            # Appendix
appendix_casimir.tex    # Specialized appendix
references.bib          # Bibliography

Phase 2: Plan Changes with Feedback Mapping

Map each piece of feedback to a concrete file + line range + action:

Always use EnterPlanMode for multi-file restructuring. Present the plan before editing.

Phase 3: Implementation Patterns

Pattern 1: Moving Content Earlier (e.g., Problem Statement to Introduction)

This is the most common revision request. The three-step protocol:

1. Add the content in its new location (e.g., new \paragraph{Problem setting.} in Introduction)
2. Slim the original location to a back-reference: "As described in Section~\ref{sec:intro}, ..."
3. Preserve all \label{} tags or update \ref{} calls

Key principle: The moved content should be a self-contained summary, not a copy-paste. The original section keeps the technical details.

Example structure for a problem-setting paragraph in the Introduction:

\paragraph{Problem setting.}
We consider the [setting name]: we observe only [what's observed]
at discrete times; [what's latent] are latent and never measured.
The goal is to [goal (a)] and [goal (b)].
[Method] addresses this via [solution sketch: 2-3 stages].
Given [input], [method] produces [output];
Section~\ref{sec:methods} details the components.

Pattern 2: Explaining Abstract Tables with Concrete Instantiations

When a table maps systems to mathematical components, add a \paragraph{Concrete instantiations.} that walks through 2-3 representative rows:

\paragraph{Concrete instantiations.}
To make the mapping from physical system to $(V, M, D)$ template explicit,
we walk through three representative entries from Table~\ref{tab:...}:
\begin{itemize}
\item \textbf{System A} (REGIME).
  State $q = ...$, momentum $p = ...$.
  [Component 1] encodes [physical meaning];
  [Component 2] is [given/learned because...];
  [Component 3] is [the unknown that method learns].

\item \textbf{System B} (DIFFERENT REGIME).
  [Same structure, different system, showing contrast]

\item \textbf{System C} (CROSS-DOMAIN).
  [Non-obvious domain to show generality]
\end{itemize}

Selection heuristic: Pick one fully-specified (KNOWN), one partially-specified (PARTIAL), and one from a surprising domain (non-mechanical, ecological, etc.).

Pattern 3: Abstract Restructuring (Problem-First)

Reviewers often complain the abstract leads with the framework instead of the problem. The canonical structure:

1. Context (1 sentence): Why this domain matters
2. Problem (1-2 sentences): What we're solving, what's observed vs. latent
3. Framework (1 sentence): The structural insight that enables the solution
4. Method (1-2 sentences): What the method does concretely
5. Results (1 sentence): Key empirical finding
6. Insight (1 sentence): What we learned (e.g., identifiability vs. forecasting)

Anti-pattern: Starting with "$\dot{x} = (J-R)\nabla H(x)$" before the reader knows what problem is being solved.

Pattern 4: Section Merging / Deduplication

When two sections overlap (e.g., Sec 3.1 and Sec 3.2 both introduce PH dynamics):

1. Identify the canonical location (usually the first occurrence)
2. Move unique content from the later section into the earlier one
3. Replace the later section with a back-reference paragraph
4. Update the section roadmap (the "This section describes..." paragraph)
5. Check all \ref{} calls to the removed/merged subsection labels

Pattern 5: Cross-File Consistency After Restructuring

After moving content between files, verify:

• Labels defined in one file aren't duplicated in another
• \ref{} calls still resolve (compile and check log)
• Notation is consistent (same macro names for the same symbols)
• Commented-out content in the original location is cleaned up or marked

Pattern 6: Cross-Reference Connectivity Audit

For a thorough review (not just compilation), audit the full cross-reference graph:

1. Grep all \label{} and \ref{} across every .tex file
2. Check label naming matches location: A label sec:methods:X should be defined in the methods section, not the introduction. Rename mislocated labels.
3. Find orphan labels: Defined but never referenced — typically fine for internal appendix structure, but flag any in the main paper
4. Find dangling refs: Referenced but not defined — even in commented-out code, these signal stale content
5. Verify back-references: If methods.tex opens with "As described in Sec 1...", confirm the label resolves to the right paragraph

Real example: sec:methods:regimes was defined in the Introduction (promoted for arXiv) but the name implied Methods. Every \ref resolved to Sec 1 when readers expected Sec 3. Renamed to sec:intro:regimes.

Pattern 7: Table Claim Verification

When a table summarizes properties (identifiability, convergence, complexity):

1. Check each cell against its detailed description in the appendix or body text
2. Flag qualified claims presented as unqualified (e.g., "Yes" when the appendix says "up to overall scale")
3. Check notation consistency: Symbols in table columns shouldn't clash with established notation (e.g., $D_0$ for mass base diagonal when $D$ is reserved for damping → rename to $m_0$)
4. Add footnotes for caveats: Use $^\dagger$ with caption text rather than silent simplification

Pattern 8: Appendix Cleanup & Prose Quality

Appendix sections often accumulate dead code and robotic prose:

1. Delete empty placeholders: Subsections that say only "Left to future work" — remove entirely
2. Clean commented-out blocks: >50 commented lines with no active content nearby → delete
3. Add regime/group headers: When listing many items back-to-back (e.g., 9 systems), group them with \paragraph{} headers and 1-2 connecting sentences
4. Fix float drift: Appendix figures with [h] or [t] often drift into the bibliography → use [H] (requires \usepackage{float})

Pattern 9: Mechanism-Before-Claim Prose

When body prose sounds like a slogan or summary card, rewrite it so the reader sees the mechanism before the claim.

Watch for sentences like:

• "This provides an interface for domain knowledge."
• "This shows the model is interpretable."
• "This is the main diagnostic lesson."
• "The result demonstrates robustness."

Replace them with the concrete chain:

• Modeling choice: what component, constraint, chart, loss, or algorithm step changes?
• Failure mode: what goes wrong without it?
• Isolating evidence: which ablation, metric, figure, or table shows the effect?
• Scope: what does the result not prove?

Example:

% Weak
Domain charts provide an interface for target manifolds.

% Stronger
If q lives on a constrained space Q, raw Euclidean coordinates make the
constraint a learned behavior rather than a structural fact.  PHAST therefore
uses a chart z = chi(q) before phase-state inference.  In predator--prey,
the log-positive chart removes negative-population rollouts and improves
H=100 error under observation noise without changing the rollout architecture.

Use contribution lists in the introduction when helpful, but avoid claim-map language in technical body paragraphs. Body paragraphs should teach the reader the mechanism, not recite the claim.

Phase 4: Compilation & Verification

Always compile after changes. The full verification workflow:

# Full build (from the paper directory)
pdflatex -interaction=nonstopmode main.tex
bibtex main
pdflatex -interaction=nonstopmode main.tex
pdflatex -interaction=nonstopmode main.tex

Post-compilation checks:

# Zero undefined references
grep -c "undefined" main.log
# Zero multiply-defined labels
grep "multiply" main.log
# Check for other warnings (filter noise)
grep -i "warning" main.log | grep -v "Font\|pdf\|Unused\|size\|rerun\|float\|empty\|draft"

Visual verification: Read the PDF pages where changes were made to confirm rendering.

Phase 5: Git Workflow (Overleaf)

For Overleaf-backed papers:

• Commit with descriptive messages referencing the feedback addressed
• Push directly to master (Overleaf syncs from master)
• Only commit .tex and .bib files; exclude build artifacts (.aux, .log, .pdf, .bbl, .blg, .out)

Common Revision Patterns by Feedback Type

"The paper doesn't state the problem clearly"

→ Pattern 1 (move to intro) + Pattern 3 (rewrite abstract)

"I don't understand what Table X means"

→ Pattern 2 (concrete instantiations)

"Sections 3.1 and 3.2 seem redundant"

→ Pattern 4 (merge + back-reference)

"The abstract is too technical / leads with equations"

→ Pattern 3 (problem-first abstract)

"The notation is introduced too late"

→ Move notation paragraph earlier; keep formal definition in Methods

LaTeX Pitfalls in Paper Revision

See PITFALLS.md for the complete reference. Critical ones:

Output Format

After implementing all revisions:

## Revision Summary

| Part | File | What Changed |
|------|------|-------------|
| A | main.tex | Abstract rewritten: problem before framework |
| B | main.tex | New "Problem setting" paragraph in Sec 1 |
| C | methods.tex | Sec 3.1 slimmed to back-reference |
| D | main.tex | Concrete instantiations for Table 1 |

Build: clean (N pages, 0 undefined refs, 0 warnings)

Progressive Disclosure

For detailed examples and pitfalls:

• PATTERNS.md — Complete before/after examples from real revisions
• PITFALLS.md — Comprehensive LaTeX pitfalls with fixes

Validation Checklist

Before marking revision complete:

• All feedback items addressed with specific file + line changes
• Full compilation passes (pdflatex + bibtex + pdflatex × 2)
• Zero undefined references in log
• Zero multiply-defined labels
• PDF visually verified on affected pages
• No redundant content between sections (no reader déjà vu)
• Abstract states the problem before the framework
• All tables with abstract entries have concrete explanations nearby
• Label names match the section they're defined in (no sec:methods:X in intro)
• Table claims match detailed text (footnote any qualified claims)
• No notation collisions across columns/sections (e.g., $D_0$ for mass vs. $D$ for damping)
• Appendix: no empty placeholder sections, no large commented-out blocks
• Appendix: figures use [H] placement (not [h]/[t] which drift)
• Git committed with descriptive message mapping to feedback