paper-writing

# Workflow 3: Paper Writing Pipeline Orchestrate a complete paper writing workflow for: **$ARGUMENTS** ## Overview This skill chains five sub-skills into a single automated pipeline: ``` /paper-plan → /paper-figure → /paper-write → /paper-compile → /auto-paper-improvement-loop (outline) (plots) (LaTeX) (build PDF) (review & polish ×2) ``` Each phase builds on the previous one's output. The final deliverable is a polished, reviewed `paper/` directory with LaTeX source and compiled PDF. ## Constants - **VENUE = `ICLR`** — Target venue. Options: `ICLR`, `NeurIPS`, `ICML`. Affects style file, page limit, citation format. - **MAX_IMPROVEMENT_ROUNDS = 2** — Number of review→fix→recompile rounds in the improvement loop. - **REVIEWER_MODEL = `gpt-5.4`** — Model used via Codex MCP for plan review, figure review, writing review, and improvement loop. - **AUTO_PROCEED = true** — Auto-continue between phases. Set `false` to pause and wait for user approval after each phase. - **HUMAN_CHECKPOINT = false** — When `true`, the improvement loop (Phase 5) pauses after each round's review to let you see the score and provide custom modification instructions. When `false` (default), the loop runs fully autonomously. Passed through to `/auto-paper-improvement-loop`. > Override inline: `/paper-writing "NARRATIVE_REPORT.md" — venue: NeurIPS, human checkpoint: true` ## Inputs This pipeline accepts one of: 1. **`NARRATIVE_REPORT.md`** (best) — structured research narrative with claims, experiments, results, figures 2. **Research direction + experiment results** — the skill will help draft the narrative first 3. **Existing `PAPER_PLAN.md`** — skip Phase 1, start from Phase 2 The more detailed the input (especially figure descriptions and quantitative results), the better the output. ## Pre-Flight: Experiment Validation Gate **BEFORE starting the paper pipeline, run `/validate-experiment` to verify:** 1. Results come from real model execution (not oracle/mock) 2. Actual simulation frames exist for visualization 3. A trained model checkpoint exists **If validation fails, DO NOT proceed.** Fix the experiments first. A paper built on fake data wastes everyone's time and will be immediately rejected. ``` /validate-experiment [project-dir] ``` Only proceed to Phase 1 if the validation report says **PROCEED**. ## Pipeline ### Phase 1: Paper Plan Invoke `/paper-plan` to create the structural outline: ``` /paper-plan "$ARGUMENTS" ``` **What this does:** - Parse NARRATIVE_REPORT.md for claims, evidence, and figure descriptions - Build a **Claims-Evidence Matrix** — every claim maps to evidence, every experiment supports a claim - Design section structure (5-8 sections depending on paper type) - Plan figure/table placement with data sources - Scaffold citation structure - GPT-5.4 reviews the plan for completeness **Output:** `PAPER_PLAN.md` with section plan, figure plan, citation scaffolding. **Checkpoint:** Present the plan summary to the user. ``` 📐 Paper plan complete: - Title: [proposed title] - Sections: [N] ([list]) - Figures: [N] auto-generated + [M] manual - Target: [VENUE], [PAGE_LIMIT] pages Shall I proceed with figure generation? ``` - **User approves** (or AUTO_PROCEED=true) → proceed to Phase 2. - **User requests changes** → adjust plan and re-present. ### Phase 2: Figure Generation Invoke `/paper-figure` to generate data-driven plots and tables: ``` /paper-figure "PAPER_PLAN.md" ``` **What this does:** - Read figure plan from PAPER_PLAN.md - Generate matplotlib/seaborn plots from JSON/CSV data - Generate LaTeX comparison tables - Create `figures/latex_includes.tex` for easy insertion - GPT-5.4 reviews figure quality and captions **Output:** `figures/` directory with PDFs, generation scripts, and LaTeX snippets. > **Scope:** Auto-generates ~60% of figures (data plots, comparison tables). Architecture diagrams, pipeline figures, and qualitative result grids must be created manually and placed in `figures/` before proceeding. See `/paper-figure` SKILL.md for details. **Checkpoint:** List generated vs manual figures. ``` 📊 Figures complete: - Auto-generated: [list] - Manual (need your input): [list] - LaTeX snippets: figures/latex_includes.tex [If manual figures needed]: Please add them to figures/ before I proceed. [If all auto]: Shall I proceed with LaTeX writing? ``` ### Phase 3: LaTeX Writing Invoke `/paper-write` to generate section-by-section LaTeX: ``` /paper-write "PAPER_PLAN.md" ``` **What this does:** - Write each section following the plan, with proper LaTeX formatting - Insert figure/table references from `figures/latex_includes.tex` - Build `references.bib` from citation scaffolding - Clean stale files from previous section structures - Automated bib cleaning (remove uncited entries) - De-AI polish (remove "delve", "pivotal", "landscape"...) - GPT-5.4 reviews each section for quality **Output:** `paper/` directory with `main.tex`, `sections/*.tex`, `references.bib`, `math_commands.tex`. **Checkpoint:** Report section completion. ``` ✍️ LaTeX writing complete: - Sections: [N] written ([list]) - Citations: [N] unique keys in references.bib - Stale files cleaned: [list, if any] Shall I proceed with compilation? ``` ### Phase 4: Compilation Invoke `/paper-compile` to build the PDF: ``` /paper-compile "paper/" ``` **What this does:** - `latexmk -pdf` with automatic multi-pass compilation - Auto-fix common errors (missing packages, undefined refs, BibTeX syntax) - Up to 3 compilation attempts - Post-compilation checks: undefined refs, page count, font embedding - Precise page verification via `pdftotext` - Stale file detection **Output:** `paper/main.pdf` **Checkpoint:** Report compilation results. ``` 🔨 Compilation complete: - Status: SUCCESS - Pages: [X] (main body) + [Y] (references) + [Z] (appendix) - Within page limit: YES/NO - Undefined references: 0 - Undefined citations: 0 Shall I proceed with the improvement loop? ``` ### Phase 5: Auto Improvement Loop Invoke `/auto-paper-improvement-loop` to polish the paper: ``` /auto-paper-improvement-loop "paper/" ``` **What this does (2 rounds):** **Round 1:** GPT-5.4 xhigh reviews the full paper → identifies CRITICAL/MAJOR/MINOR issues → Claude Code implements fixes → recompile → save `main_round1.pdf` **Round 2:** GPT-5.4 xhigh re-reviews with conversation context → identifies remaining issues → Claude Code implements fixes → recompile → save `main_round2.pdf` **Typical improvements:** - Fix assumption-model mismatches - Soften overclaims to match evidence - Add missing interpretations and notation - Strengthen limitations section - Add theory-aligned experiments if needed **Output:** Three PDFs for comparison + `PAPER_IMPROVEMENT_LOG.md`. **Format check** (included in improvement loop Step 8): After final recompilation, auto-detect and fix overfull hboxes (content exceeding margins), verify page count vs venue limit, and ensure compact formatting. Any overfull > 10pt is fixed before generating the final PDF. ### Phase 6: Final Report ```markdown # Paper Writing Pipeline Report **Input**: [NARRATIVE_REPORT.md or topic] **Venue**: [ICLR/NeurIPS/ICML] **Date**: [today] ## Pipeline Summary | Phase | Status | Output | |-------|--------|--------| | 1. Paper Plan | ✅ | PAPER_PLAN.md | | 2. Figures | ✅ | figures/ ([N] auto + [M] manual) | | 3. LaTeX Writing | ✅ | paper/sections/*.tex ([N] sections, [M] citations) | | 4. Compilation | ✅ | paper/main.pdf ([X] pages) | | 5. Improvement | ✅ | [score0]/10 → [score2]/10 | ## Improvement Scores | Round | Score | Key Changes | |-------|-------|-------------| | Round 0 | X/10 | Baseline | | Round 1 | Y/10 | [summary] | | Round 2 | Z/10 | [summary] | ## Deliverables - paper/main.pdf — Final polished paper - paper/main_round0_original.pdf — Before improvement - paper/main_round1.pdf — After round 1 - paper/main_round2.pdf — After round 2 - paper/PAPER_IMPROVEMENT_LOG.md — Full review log ## Remaining Issues (if any) - [items from final review that weren't addressed] ## Next Steps - [ ] Visual inspection of PDF - [ ] Add any missing manual figures - [ ] Submit to [venue] via OpenReview / CMT / HotCRP ``` ## Key Rules - **Don't skip phases.** Each phase builds on the previous one — skipping leads to errors. - **Checkpoint between phases** when AUTO_PROCEED=false. Present results and wait for approval. - **Manual figures first.** If the paper needs architecture diagrams or qualitative results, the user must provide them before Phase 3. - **Compilation must succeed** before entering the improvement loop. Fix all errors first. - **Preserve all PDFs.** The user needs round0/round1/round2 for comparison. - **Document everything.** The pipeline report should be self-contained. - **Respect page limits.** If the paper exceeds the venue limit, suggest specific cuts before the improvement loop. ## Composing with Other Workflows ``` /idea-discovery "direction" ← Workflow 1: find ideas implement ← write code /run-experiment ← deploy experiments /auto-review-loop "paper topic" ← Workflow 2: iterate research /paper-writing "NARRATIVE_REPORT.md" ← Workflow 3: you are here submit! 🎉 Or use /research-pipeline for the Workflow 1+2 end-to-end flow, then /paper-writing for the final writing step. ``` ## Typical Timeline | Phase | Duration | Can sleep? | |-------|----------|------------| | 1. Paper Plan | 5-10 min | No | | 2. Figures | 5-15 min | No | | 3. LaTeX Writing | 15-30 min | Yes ✅ | | 4. Compilation | 2-5 min | No | | 5. Improvement | 15-30 min | Yes ✅ | **Total: ~45-90 min** for a full paper from narrative report to polished PDF.