refining-ml-papers
Skill2 starsChanged 6 months agoMITView on GitHub
Refines ML/scientific LaTeX papers based on reviewer or advisor feedback. Handles structural reorganization (moving problem statements, merging sections), concrete instantiations of abstract tables, cross-file deduplication, and compilation verification. Use when the user requests paper revisions, addresses reviewer comments, restructures sections, or improves exposition clarity.
In this repository10 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 22 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈22
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Before making ANY changes:
- Very specific: line 31
Check for shared macros: Look for \providecommand / \newcommand patterns that indicate cross-file dependencies
- Distinctive: line 73
Keep essential reproduction details in research prose and implementation provenance in supporting records.
- Distinctive: line 84
When a before/after artifact is requested, resolve each version's references against its own build.
- Distinctive: line 88
Use the project's existing revision tooling instead of inventing a parallel system.
- Very specific: line 115
When a table maps systems to mathematical components, add a \paragraph{Concrete instantiations.} that walks through 2-3 representative rows:
- Distinctive: line 153
When two sections overlap (e.g., Sec 3.1 and Sec 3.2 both introduce PH dynamics):
- Distinctive: line 163
After moving content between files, verify:
- Distinctive: line 178
Verify back-references: If methods.tex opens with "As described in Sec 1...", confirm the label resolves to the right paragraph
- Distinctive: line 184
When a table summarizes properties (identifiability, convergence, complexity):
- Very specific: line 189
Add footnotes for caveats: Use $^\dagger$ with caption text rather than silent simplification
- Very specific: line 197
Add regime/group headers: When listing many items back-to-back (e.g., 9 systems), group them with \paragraph{} headers and 1-2 connecting …
- Distinctive: line 202
When body prose sounds like a slogan or summary card, rewrite it so the reader sees the mechanism before the claim.
- Distinctive: line 231
Use contribution lists in the introduction when helpful, but avoid claim-map language in technical body paragraphs.
- Distinctive: line 237
When a paper feels assembled from good pieces but the story does not flow, rebuild the narrative around failure modes.
- Distinctive: line 248
Avoid organizing the main narrative as a survey of model families.
- Distinctive: line 256
add short semantic comments for each logical chunk
- Distinctive: line 259
keep wrapper logic, inner kernels, and training objectives in separate algorithms if combining them hurts readability
- Distinctive: line 262
If a figure and algorithm describe the same pipeline, use the same nouns, order, colors, and symbols in both.
- Distinctive: line 266
Before adding or revising a figure, ask whether it merely describes the paper or shows the surprising behavior.
- Distinctive: line 268
Prefer figures that reveal:
- Distinctive: line 282
Avoid terms like "pilot", "scoped", "chunk_crouch", "freeze=none", "action-veto pilot", or "we do not claim anything" in polished prose.
- Distinctive: line 284
Use explicit information contracts and method names instead:
- Distinctive: line 327
Do not assume a branch named master, discard unrelated work, or silently resolve divergence.
- Distinctive: line 362
After implementing all revisions:
- Distinctive: line 386
Before marking revision complete:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
- Map the file structure:
Globfor**/*.texto find all LaTeX files - Identify the main file and all
\input{}dependencies - Read the target sections completely before editing
- Check for shared macros: Look for
\providecommand/\newcommandpatterns that indicate cross-file dependencies - Note existing labels:
Grepfor\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 # BibliographyPhase 2: Plan Changes with Feedback Mapping
Map each piece of feedback to a concrete file + line range + action:
| Feedback | Action | File(s) | Risk |
| "Problem statement too late" | Move to Sec 1 + slim Sec 3 | main.tex + methods.tex | Cross-ref breakage |
| "Table entries unclear" | Add concrete instantiations paragraph | main.tex | None |
| "Sections redundant" | Merge + back-reference | methods.tex | Label conflicts |
| "Abstract doesn't state problem" | Restructure abstract | main.tex | None |
For multi-file restructuring, present the plan before editing and obtain any approval required by the user's workflow. Use available planning tools when helpful; do not depend on a tool that the current host does not provide.
For a substantial narrative repair, rehearse the argument with an existing deck
or a short slide-level storyboard before polishing paragraphs. Preserve the
teaching dependencies, not one paragraph per slide. Use rigorous-paper-author
for the story brief and explain-systems-visually for a rendered teaching deck
when those skills are available; neither is mandatory for a small correction.
Phase 2a: Make the revision reversible
For substantial revisions and requested before/after reviewer comparisons, use the shared comparison protocol. The workflow is baseline preservation, approved edits, a rendered frozen pair, authorized independent content/flow reviews, reasoned version preferences, approved repairs, and final verification. Preserve the reviewed pair when producing a refinement; do not overwrite the evidence reviewers assessed. Keep essential reproduction details in research prose and implementation provenance in supporting records. Small corrections need proportionate checks, not an automatic reviewer panel.
Compare claims and structure explicitly: current claim, proposed claim, why, and exactly what is retained, moved, narrowed, or removed. Separate wording repairs from evidence gaps; do not fill a pending result with an anticipated win. Preserve a named source snapshot or scoped patch against the immediate current draft, including pre-existing edits. Do not treat an old published version as the baseline when the user is reviewing an intervening revision.
When a before/after artifact is requested, resolve each version's references against its own build. Red/blue text should also have explicit Before/After labels. Keep result values, assumptions, equations, and unique contributions accounted for even when relocated. Confirm the preservation record after edits. Use the project's existing revision tooling instead of inventing a parallel system.
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:
- Add the content in its new location (e.g., new
\paragraph{Problem setting.}in Introduction) - Slim the original location to a back-reference: "As described in Section~\ref{sec:intro}, ..."
- 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:
- Context (1 sentence): Why this domain matters
- Problem (1-2 sentences): What we're solving, what's observed vs. latent
- Framework (1 sentence): The structural insight that enables the solution
- Method (1-2 sentences): What the method does concretely
- Results (1 sentence): Key empirical finding
- 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):
- Identify the canonical location (usually the first occurrence)
- Move unique content from the later section into the earlier one
- Replace the later section with a back-reference paragraph
- Update the section roadmap (the "This section describes..." paragraph)
- 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:
- Grep all
\label{}and\ref{}across every.texfile - Check label naming matches location: A label
sec:methods:Xshould be defined in the methods section, not the introduction. Rename mislocated labels. - Find orphan labels: Defined but never referenced — typically fine for internal appendix structure, but flag any in the main paper
- Find dangling refs: Referenced but not defined — even in commented-out code, these signal stale content
- 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):
- Check each cell against its detailed description in the appendix or body text
- Flag qualified claims presented as unqualified (e.g., "Yes" when the appendix says "up to overall scale")
- 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$)
- 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:
- Delete empty placeholders: Subsections that say only "Left to future work" — remove entirely
- Clean commented-out blocks: >50 commented lines with no active content nearby → delete
- 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 - 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.
Pattern 10: Failure-Mode-Driven Reframing
When a paper feels assembled from good pieces but the story does not flow, rebuild the narrative around failure modes.
Use this sequence:
- Name the operational failure mode in the introduction.
- State why existing work fails under that condition.
- Introduce the method component that addresses it.
- Cross-reference the algorithm chunk where the component is executed.
- Cross-reference the experiment, table, or figure that isolates the fix.
- State the scope boundary without weakening the core claim.
Avoid organizing the main narrative as a survey of model families. Related work can use literature categories, but the introduction and method should use the problem-to-component-to-evidence chain.
Pattern 11: Algorithm and Figure Continuity
Algorithms should look like executable versions of the method diagram.
For complex scientific ML methods:
- add short semantic comments for each logical chunk
- color comments consistently with the corresponding figure block when the paper already uses colored diagrams
- cite the equation or subsection that defines each nontrivial update
- keep wrapper logic, inner kernels, and training objectives in separate algorithms if combining them hurts readability
- make the algorithm title honest: deployed transition, training objective, helper solve, critic interface, etc.
If a figure and algorithm describe the same pipeline, use the same nouns, order, colors, and symbols in both.
Pattern 12: Figures Should Show the Surprise
Before adding or revising a figure, ask whether it merely describes the paper or shows the surprising behavior.
Prefer figures that reveal:
- a failure mode that standard metrics hide
- a decomposition that only the proposed model exposes
- a visual before/after from one modeling choice
- a baseline breakdown under a realistic deployment condition
- a typed residual, energy ledger, or physical accounting signal that a black-box model cannot produce
Architecture diagrams are useful, but a teaser or main-result figure should usually show the phenomenon the reader should remember.
Pattern 13: Research-Native Scope Language
Replace implementation-coded or timid language with precise research language.
Avoid terms like "pilot", "scoped", "chunk_crouch", "freeze=none", "action-veto pilot", or "we do not claim anything" in polished prose.
Use explicit information contracts and method names instead:
- "q-history deployment" instead of "q-only mode" when the contract matters
- "receding-window observer" instead of "reobserve hack"
- "template-known estimator" instead of "oracle-ish baseline"
- "model-predictive critic" instead of "action-veto pilot"
- "all parameters updated" / "core transition fixed" instead of code flags
Limitations should name the boundary and preserve the claim: what was tested, what information each method received, and what remains for later work.
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.texPost-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: Inspect the rendered PDF pages where changes were made, including affected float and page-break neighbors. Check the before/after review as well as the clean output. Sweep repeated defects, not only the reported instance. Compilation and reference checks do not establish visual quality or comprehension.
Phase 5: Git Workflow (Overleaf)
Inspect the actual repository, branch, remote, and existing changes before any Git operation. Editing authority is not automatic commit or push authority; respect a request to publish later. When publication is authorized, select only the intended changes and follow that repository's branch and artifact policies. Do not assume a branch named master, discard unrelated work, or silently resolve divergence. Preserve source figures and required assets according to the project; exclude transient build files unless its policy explicitly requires them.
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 references/PITFALLS.md for the complete reference. Critical ones:
| Issue | Cause | Fix |
| xcolor option clash | Style file loads xcolor; you also load it | \PassOptionsToPackage{table}{xcolor} BEFORE \usepackage{icml2026} |
Undefined \ref after merge | Label moved to different file | Check \label{} exists in the new location |
table* in single-column | Switched from two-column to one-column | Replace table* → table, figure* → figure |
| Multiply-defined labels | Merged sections both had \label{sec:ph} | Rename one; update all \ref{} calls |
\providecommand doesn't override | Macro already defined in preamble | Use \renewcommand or define only in preamble |
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:
references/PATTERNS.md— Complete before/after examples from real revisionsreferences/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
- Introduction maps failure modes to method components and evidence
- Main claims are supported in main text, not only by appendix-only evidence
- Baselines and ablations state their information contracts
- Algorithms use the same symbols/order/nouns as the method text and figures
- Algorithm comments cite equations or subsections for nontrivial chunks
- Figures show a mechanism, failure mode, or result rather than duplicating prose
- All tables with abstract entries have concrete explanations nearby
- Label names match the section they're defined in (no
sec:methods:Xin 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

