@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/paper-compile/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: "paper-compile"
+description: "Compile LaTeX paper to PDF, fix errors, and verify output. Use when user says \\\"\u7f16\u8bd1\u8bba\u6587\\\", \\\"compile paper\\\", \\\"build PDF\\\", \\\"\u751f\u6210PDF\\\", or wants to compile LaTeX into a submission-ready PDF."
+---
+
+# Paper Compile: LaTeX to Submission-Ready PDF
+
+Compile the LaTeX paper and fix any issues: **$ARGUMENTS**
+
+## Constants
+
+- **COMPILER = `latexmk`** — LaTeX build tool. Handles multi-pass compilation automatically.
+- **ENGINE = `pdflatex`** — LaTeX engine. Options: `pdflatex` (default), `xelatex` (for CJK/custom fonts), `lualatex`.
+- **MAX_COMPILE_ATTEMPTS = 3** — Maximum attempts to fix errors and recompile.
+- **PAPER_DIR = `paper/`** — Directory containing LaTeX source files.
+- **MAX_PAGES** — Page limit. ML conferences: main body to Conclusion end (excluding references & appendix). ICLR=9, NeurIPS=9, ICML=8. **IEEE venues: references ARE included in page count.** IEEE journal ≈ 12-14 pages, IEEE conference ≈ 5-8 pages (all inclusive).
+- **RESCUE_ON_REPEAT_FAILURE = true** — If the same compile class fails after two attempts, preserve `compile.log` and ask for a focused rescue / second opinion before further edits.
+
+## Workflow
+
+### Step 1: Verify Prerequisites
+
+Check that the compilation environment is ready:
+
+```bash
+# Check LaTeX installation
+which pdflatex && which latexmk && which bibtex
+
+# If not installed, provide instructions:
+# macOS: brew install --cask mactex-no-gui
+# Ubuntu: sudo apt-get install texlive-full
+# Server: conda install -c conda-forge texlive-core
+```
+
+Verify all required files exist:
+
+```bash
+# Must exist
+ls $PAPER_DIR/main.tex
+
+# Should exist
+ls $PAPER_DIR/references.bib
+ls $PAPER_DIR/sections/*.tex
+ls $PAPER_DIR/figures/*.pdf 2>/dev/null || ls $PAPER_DIR/figures/*.png 2>/dev/null
+```
+
+### Step 2: First Compilation Attempt
+
+```bash
+cd $PAPER_DIR
+
+# Clean previous build artifacts
+latexmk -C
+
+# Full compilation (pdflatex + bibtex + pdflatex × 2)
+latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex 2>&1 | tee compile.log
+```
+
+### Step 3: Error Diagnosis and Auto-Fix
+
+If compilation fails, read `compile.log` and fix common errors:
+
+**Missing packages:**
+```
+! LaTeX Error: File `somepackage.sty' not found.
+```
+→ Install via `tlmgr install somepackage` or remove the `\usepackage` if unused.
+
+**Undefined references:**
+```
+LaTeX Warning: Reference `fig:xyz' on page 3 undefined
+```
+→ Check `\label{fig:xyz}` exists in the correct figure environment.
+
+**Missing figures:**
+```
+! LaTeX Error: File `figures/fig1.pdf' not found.
+```
+→ Check if the file exists with a different extension (.png vs .pdf). Update the `\includegraphics` path.
+
+**Citation undefined:**
+```
+LaTeX Warning: Citation `smith2024' undefined
+```
+→ Add the missing entry to `references.bib` or fix the citation key.
+
+**`[VERIFY]` markers in text:**
+→ Search for `[VERIFY]` markers left by `/paper-write`. These indicate unverified citations or facts. Search for the correct information or flag to the user.
+
+**Overfull hbox:**
+```
+Overfull \hbox (12.5pt too wide) in paragraph at lines 42--45
+```
+→ Minor: usually ignorable. If severe (>20pt), rephrase the text or adjust figure width.
+
+**BibTeX errors:**
+```
+I was expecting a `,' or a `}'---line 15 of references.bib
+```
+→ Fix BibTeX syntax (missing comma, unmatched braces, special characters in title).
+
+**`\crefname` undefined for custom theorem types:**
+→ Ensure `\crefname{assumption}{Assumption}{Assumptions}` and similar are in the preamble after `\newtheorem{assumption}`.
+
+### Step 4: Iterative Fix Loop
+
+```
+for attempt in 1..MAX_COMPILE_ATTEMPTS:
+    compile()
+    if success:
+        break
+    parse_errors()
+    auto_fix()
+```
+
+For each error:
+1. Read the error message from `compile.log`
+2. Locate the source file and line number
+3. Apply the fix
+4. Recompile
+
+### Step 5: Post-Compilation Checks
+
+After successful compilation, verify the output:
+
+```bash
+# Check PDF exists and has content
+ls -la main.pdf
+# Check page count
+pdfinfo main.pdf | grep Pages
+
+# macOS: open for visual inspection
+# open main.pdf
+```
+
+**Automated checks:**
+
+- [ ] PDF file exists and is > 100KB (not empty/corrupt)
+- [ ] Total page count is reasonable (MAX_PAGES + appendix + references)
+- [ ] No "??" in the PDF (undefined references — grep the log)
+- [ ] No "[?]" in the PDF (undefined citations — grep the log)
+- [ ] Figures are rendered (not missing image placeholders)
+
+```bash
+# Check for undefined references
+grep -c "LaTeX Warning.*undefined" compile.log
+
+# Check for missing citations
+grep -c "Citation.*undefined" compile.log
+```
+
+### Step 6: Page Count Verification
+
+**CRITICAL**: Verify paper fits within MAX_PAGES.
+
+**For ML conferences (ICLR/NeurIPS/ICML/CVPR/ACL/AAAI):** Main body = first page through end of Conclusion section (not necessarily §5 — could be §6, §7, or §8 depending on structure). References and appendix are NOT counted.
+
+**For IEEE venues:** The TOTAL page count (including references) must fit within the limit. There is no separate "main body" counting — everything up to and including the references counts.
+
+**Precise check using `pdftotext`:**
+```bash
+# Extract text and find where Conclusion ends vs References begin
+pdftotext main.pdf - | python3 -c "
+import sys
+text = sys.stdin.read()
+pages = text.split('\f')
+for i, page in enumerate(pages):
+    if 'Ethics Statement' in page or 'Reproducibility' in page:
+        print(f'Conclusion ends on page {i+1}')
+    if any(w in page for w in ['References', 'Bibliography']):
+        lines = [l for l in page.split('\n') if l.strip()]
+        for l in lines[:3]:
+            if 'References' in l or 'Bibliography' in l:
+                print(f'References start on page {i+1}')
+                break
+"
+```
+
+If Conclusion ends mid-page and References start on the same page, the main body is that page number (e.g., if both are on page 9, main body = ~8.5 pages, which is fine for a 9-page limit since it leaves room for the References header).
+
+If over limit:
+- Identify which sections are longest
+- Suggest specific cuts (move proofs to appendix, compress tables, tighten writing)
+- Report: "Main body is X pages (limit: MAX_PAGES). Suggestion: move [specific content] to appendix."
+
+### Step 6.5: Stale File Detection
+
+Check for orphaned section files not referenced by `main.tex`:
+
+```bash
+# Find all .tex files in sections/ and check which are \input'ed by main.tex
+for f in paper/sections/*.tex; do
+    base=$(basename "$f")
+    if ! grep -q "$base" paper/main.tex; then
+        echo "WARNING: $f is not referenced by main.tex — consider removing"
+    fi
+done
+```
+
+This prevents confusion from leftover files when section structure changes (e.g., old `5_conclusion.tex` left behind after restructuring to 7 sections).
+
+### Step 7: Submission Readiness
+
+For conference submission, additional checks:
+
+- [ ] **Anonymous**: no author names, affiliations, or self-citations that reveal identity
+- [ ] **Page limit**: main body within MAX_PAGES (to end of Conclusion)
+- [ ] **Font embedding**: all fonts embedded in PDF
+  ```bash
+  pdffonts main.pdf | grep -v "yes"  # should return nothing (or only header)
+  ```
+- [ ] **No supplementary mixed in**: appendix clearly after `\newpage\appendix`
+- [ ] **File size**: reasonable (< 50MB for most venues, < 10MB preferred)
+- [ ] **No `[VERIFY]` markers**: search the PDF text for leftover markers
+
+### Step 8: Output Summary
+
+```markdown
+## Compilation Report
+
+- **Status**: SUCCESS / FAILED
+- **PDF**: paper/main.pdf
+- **Pages**: X (main body to Conclusion) + Y (references) + Z (appendix)
+- **Within page limit**: YES/NO (MAX_PAGES = N)
+- **Errors fixed**: [list of auto-fixed issues]
+- **Warnings remaining**: [list of non-critical warnings]
+- **Undefined references**: 0
+- **Undefined citations**: 0
+
+### Next Steps
+- [ ] Visual inspection of PDF
+- [ ] Run `/paper-write` to fix any content issues
+- [ ] Submit to [venue] via OpenReview / CMT / HotCRP
+```
+
+## Key Rules
+
+- **Never delete the user's source files** — only modify to fix errors
+- **Keep compile.log** — useful for debugging
+- **Don't suppress warnings** — report them, let the user decide
+- **If LaTeX is not installed**, provide clear installation instructions rather than failing silently
+- **Font embedding is critical** — some venues reject PDFs with non-embedded fonts
+- **Page count rules differ by venue** — ML conferences: main body to Conclusion (refs excluded). **IEEE venues: total pages including references.**
+
+## Common Venue Requirements
+
+| Venue | Style File | Citation | Page Limit | Refs in limit? | Submission |
+|-------|-----------|----------|------------|----------------|------------|
+| ICLR 2026 | `iclr2026_conference.sty` | `natbib` (`\citep`/`\citet`) | 9 pages (to Conclusion end) | No | OpenReview |
+| NeurIPS 2025 | `neurips_2025.sty` | `natbib` (`\citep`/`\citet`) | 9 pages (to Conclusion end) | No | OpenReview |
+| ICML 2025 | `icml2025.sty` | `natbib` (`\citep`/`\citet`) | 8 pages (to Conclusion end) | No | OpenReview |
+| IEEE Journal | `IEEEtran.cls` [journal] | `cite` (`\cite{}`, numeric) | ~12-14 pages (Transactions) / ~4-5 (Letters) | **Yes** | IEEE Author Portal / ScholarOne |
+| IEEE Conference | `IEEEtran.cls` [conference] | `cite` (`\cite{}`, numeric) | 5-8 pages (varies by conf) | **Yes** | EDAS / IEEE Author Portal |

package/dist/skills/paper-figure/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: "paper-figure"
+description: "Generate publication-quality figures and tables from experiment results. Use when user says \\\"\u753b\u56fe\\\", \\\"\u4f5c\u56fe\\\", \\\"generate figures\\\", \\\"paper figures\\\", or needs plots for a paper."
+---
+
+# Paper Figure: Publication-Quality Plots from Experiment Data
+
+Generate all figures and tables for a paper based on: **$ARGUMENTS**
+
+## Scope: What This Skill Can and Cannot Do
+
+| Category | Can auto-generate? | Examples |
+|----------|-------------------|----------|
+| **Data-driven plots** | ✅ Yes | Line plots (training curves), bar charts (method comparison), scatter plots, heatmaps, box/violin plots |
+| **Comparison tables** | ✅ Yes | LaTeX tables comparing prior bounds, method features, ablation results |
+| **Multi-panel figures** | ✅ Yes | Subfigure grids combining multiple plots (e.g., 3×3 dataset × method) |
+| **Architecture/pipeline diagrams** | ❌ No — manual | Model architecture, data flow diagrams, system overviews. At best can generate a rough TikZ skeleton, but **expect to draw these yourself** using tools like draw.io, Figma, or TikZ |
+| **Generated image grids** | ❌ No — manual | Grids of generated samples (e.g., GAN/diffusion outputs). These come from running your model, not from this skill |
+| **Photographs / screenshots** | ❌ No — manual | Real-world images, UI screenshots, qualitative examples |
+
+**In practice:** For a typical ML paper, this skill handles ~60% of figures (all data plots + tables). The remaining ~40% (hero figure, architecture diagram, qualitative results) need to be created manually and placed in `figures/` before running `/paper-write`. The skill will detect these as "existing figures" and preserve them.
+
+## Constants
+
+- **STYLE = `publication`** — Visual style preset. Options: `publication` (default, clean for print), `poster` (larger fonts), `slide` (bold colors)
+- **DPI = 300** — Output resolution
+- **FORMAT = `pdf`** — Output format. Options: `pdf` (vector, best for LaTeX), `png` (raster fallback)
+- **COLOR_PALETTE = `tab10`** — Default matplotlib color cycle. Options: `tab10`, `Set2`, `colorblind` (deuteranopia-safe)
+- **FONT_SIZE = 10** — Base font size (matches typical conference body text)
+- **FIG_DIR = `figures/`** — Output directory for generated figures
+- **REVIEWER_MODEL = `gpt-5.5`** — Model used via a secondary Codex agent for figure quality review.
+
+## Inputs
+
+1. **PAPER_PLAN.md** — figure plan table (from `/paper-plan`)
+2. **Experiment data** — JSON files, CSV files, or screen logs in `figures/` or project root
+3. **Existing figures** — any manually created figures to preserve
+
+If no PAPER_PLAN.md exists, scan for data files and ask the user which figures to generate.
+
+## Workflow
+
+### Step 1: Read Figure Plan
+
+Parse the Figure Plan table from PAPER_PLAN.md:
+
+```markdown
+| ID | Type | Description | Data Source | Priority |
+|----|------|-------------|-------------|----------|
+| Fig 1 | Architecture | ... | manual | HIGH |
+| Fig 2 | Line plot | ... | figures/exp.json | HIGH |
+```
+
+Identify:
+- Which figures can be auto-generated from data
+- Which need manual creation (architecture diagrams, etc.)
+- Which are comparison tables (generate as LaTeX)
+
+### Step 2: Set Up Plotting Environment
+
+Create a shared style configuration script:
+
+```python
+# paper_plot_style.py — shared across all figure scripts
+import matplotlib.pyplot as plt
+import matplotlib
+matplotlib.rcParams.update({
+    'font.size': FONT_SIZE,
+    'font.family': 'serif',
+    'font.serif': ['Times New Roman', 'Times', 'DejaVu Serif'],
+    'axes.labelsize': FONT_SIZE,
+    'axes.titlesize': FONT_SIZE + 1,
+    'xtick.labelsize': FONT_SIZE - 1,
+    'ytick.labelsize': FONT_SIZE - 1,
+    'legend.fontsize': FONT_SIZE - 1,
+    'figure.dpi': DPI,
+    'savefig.dpi': DPI,
+    'savefig.bbox': 'tight',
+    'savefig.pad_inches': 0.05,
+    'axes.grid': False,
+    'axes.spines.top': False,
+    'axes.spines.right': False,
+    'text.usetex': False,  # set True if LaTeX is available
+    'mathtext.fontset': 'stix',
+})
+
+# Color palette
+COLORS = plt.cm.tab10.colors  # or Set2, or colorblind-safe
+
+def save_fig(fig, name, fmt=FORMAT):
+    """Save figure to FIG_DIR with consistent naming."""
+    fig.savefig(f'{FIG_DIR}/{name}.{fmt}')
+    print(f'Saved: {FIG_DIR}/{name}.{fmt}')
+```
+
+### Step 3: Auto-Select Figure Type
+
+Use this decision tree for data-driven figures (inspired by Imbad0202/academic-research-skills):
+
+| Data Pattern | Recommended Type | Size |
+|-------------|-----------------|------|
+| X=time/steps, Y=metric | Line plot | 0.48\textwidth |
+| Methods × 1 metric | Bar chart | 0.48\textwidth |
+| Methods × multiple metrics | Grouped bar / radar | 0.95\textwidth |
+| Two continuous variables | Scatter plot | 0.48\textwidth |
+| Matrix / grid values | Heatmap | 0.48\textwidth |
+| Distribution comparison | Box/violin plot | 0.48\textwidth |
+| Multi-dataset results | Multi-panel (subfigure) | 0.95\textwidth |
+| Prior work comparison | LaTeX table | — |
+
+### Step 4: Generate Each Figure
+
+For each figure in the plan, create a standalone Python script:
+
+**Line plots** (training curves, scaling):
+```python
+# gen_fig2_training_curves.py
+from paper_plot_style import *
+import json
+
+with open('figures/exp_results.json') as f:
+    data = json.load(f)
+
+fig, ax = plt.subplots(1, 1, figsize=(5, 3.5))
+ax.plot(data['steps'], data['fac_loss'], label='Factorized', color=COLORS[0])
+ax.plot(data['steps'], data['crf_loss'], label='CRF-LR', color=COLORS[1])
+ax.set_xlabel('Training Steps')
+ax.set_ylabel('Cross-Entropy Loss')
+ax.legend(frameon=False)
+save_fig(fig, 'fig2_training_curves')
+```
+
+**Bar charts** (comparison, ablation):
+```python
+fig, ax = plt.subplots(1, 1, figsize=(5, 3))
+methods = ['Baseline', 'Method A', 'Method B', 'Ours']
+values = [82.3, 85.1, 86.7, 89.2]
+bars = ax.bar(methods, values, color=[COLORS[i] for i in range(len(methods))])
+ax.set_ylabel('Accuracy (%)')
+# Add value labels on bars
+for bar, val in zip(bars, values):
+    ax.text(bar.get_x() + bar.get_width()/2, bar.get_height() + 0.3,
+            f'{val:.1f}', ha='center', va='bottom', fontsize=FONT_SIZE-1)
+save_fig(fig, 'fig3_comparison')
+```
+
+**Comparison tables** (LaTeX, for theory papers):
+```latex
+\begin{table}[t]
+\centering
+\caption{Comparison of estimation error bounds. $n$: sample size, $D$: ambient dim, $d$: latent dim, $K$: subspaces, $n_k$: modes.}
+\label{tab:bounds}
+\begin{tabular}{lccc}
+\toprule
+Method & Rate & Depends on $D$? & Multi-modal? \\
+\midrule
+\citet{MinimaxOkoAS23} & $n^{-s'/D}$ & Yes (curse) & No \\
+\citet{ScoreMatchingdistributionrecovery} & $n^{-2/d}$ & No & No \\
+\textbf{Ours} & $\sqrt{\sum n_k d_k / n}$ & No & Yes \\
+\bottomrule
+\end{tabular}
+\end{table}
+```
+
+**Architecture/pipeline diagrams** (MANUAL — outside this skill's scope):
+- These require manual creation using draw.io, Figma, Keynote, or TikZ
+- This skill can generate a rough TikZ skeleton as a starting point, but **do not expect publication-quality results**
+- If the figure already exists in `figures/`, preserve it and generate only the LaTeX `\includegraphics` snippet
+- Flag as `[MANUAL]` in the figure plan and `latex_includes.tex`
+
+### Step 5: Run All Scripts
+
+```bash
+# Run all figure generation scripts
+for script in gen_fig*.py; do
+    python "$script"
+done
+```
+
+Verify all output files exist and are non-empty.
+
+### Step 6: Generate LaTeX Include Snippets
+
+For each figure, output the LaTeX code to include it:
+
+```latex
+% === Fig 2: Training Curves ===
+\begin{figure}[t]
+    \centering
+    \includegraphics[width=0.48\textwidth]{figures/fig2_training_curves.pdf}
+    \caption{Training curves comparing factorized and CRF-LR denoising.}
+    \label{fig:training_curves}
+\end{figure}
+```
+
+Save all snippets to `figures/latex_includes.tex` for easy copy-paste into the paper.
+
+### Step 7: Figure Quality Review with REVIEWER_MODEL
+
+Send figure descriptions and captions to GPT-5.5 for review:
+
+```
+spawn_agent:
+  model: gpt-5.5
+  reasoning_effort: xhigh
+  message: |
+    Review these figure/table plans for a [VENUE] submission.
+
+    For each figure:
+    1. Is the caption informative and self-contained?
+    2. Does the figure type match the data being shown?
+    3. Is the comparison fair and clear?
+    4. Any missing baselines or ablations?
+    5. Would a different visualization be more effective?
+
+    [list all figures with captions and descriptions]
+```
+
+### Step 8: Quality Checklist
+
+Before finishing, verify each figure (from pedrohcgs/claude-code-my-workflow):
+
+- [ ] Font size readable at printed paper size (not too small)
+- [ ] Colors distinguishable in grayscale (print-friendly)
+- [ ] **No title inside figures** — titles go only in LaTeX `\caption{}` (from pedrohcgs)
+- [ ] Legend does not overlap data
+- [ ] Axis labels have units where applicable
+- [ ] Axis labels are publication-quality (not variable names like `emp_rate`)
+- [ ] Figure width fits single column (0.48\textwidth) or full width (0.95\textwidth)
+- [ ] PDF output is vector (not rasterized text)
+- [ ] No matplotlib default title (remove `plt.title` for publications)
+- [ ] Serif font matches paper body text (Times / Computer Modern)
+- [ ] Colorblind-accessible (if using colorblind palette)
+
+## Output
+
+```
+figures/
+├── paper_plot_style.py          # shared style config
+├── gen_fig1_architecture.py     # per-figure scripts
+├── gen_fig2_training_curves.py
+├── gen_fig3_comparison.py
+├── fig1_architecture.pdf        # generated figures
+├── fig2_training_curves.pdf
+├── fig3_comparison.pdf
+├── latex_includes.tex           # LaTeX snippets for all figures
+└── TABLE_*.tex                  # standalone table LaTeX files
+```
+
+## Key Rules
+
+- **Every figure must be reproducible** — save the generation script alongside the output
+- **Do NOT hardcode data** — always read from JSON/CSV files
+- **Use vector format (PDF)** for all plots — PNG only as fallback
+- **No decorative elements** — no background colors, no 3D effects, no chart junk
+- **Consistent style across all figures** — same fonts, colors, line widths
+- **Colorblind-safe** — verify with https://davidmathlogic.com/colorblind/ if needed
+- **One script per figure** — easy to re-run individual figures when data changes
+- **No titles inside figures** — captions are in LaTeX only
+- **Comparison tables count as figures** — generate them as standalone .tex files
+
+## Figure Type Reference
+
+| Type | When to Use | Typical Size |
+|------|------------|--------------|
+| Line plot | Training curves, scaling trends | 0.48\textwidth |
+| Bar chart | Method comparison, ablation | 0.48\textwidth |
+| Grouped bar | Multi-metric comparison | 0.95\textwidth |
+| Scatter plot | Correlation analysis | 0.48\textwidth |
+| Heatmap | Attention, confusion matrix | 0.48\textwidth |
+| Box/violin | Distribution comparison | 0.48\textwidth |
+| Architecture | System overview | 0.95\textwidth |
+| Multi-panel | Combined results (subfigures) | 0.95\textwidth |
+| Comparison table | Prior bounds vs. ours (theory) | full width |
+
+## Acknowledgements
+
+Design pattern (type × style matrix) inspired by [baoyu-skills](https://github.com/jimliu/baoyu-skills). Publication style defaults and figure rules from [pedrohcgs/claude-code-my-workflow](https://github.com/pedrohcgs/claude-code-my-workflow). Visualization decision tree from [Imbad0202/academic-research-skills](https://github.com/Imbad0202/academic-research-skills).
+