paper-figure skill

Override for Codex users who want Claude Code, not a second Codex agent, to act as the reviewer. Install this package after skills/skills-codex/*.

This reviewer is a different model family from the Codex executor. Every overlay trace/audit records:

yaml

review_independence: cross-family

acceptance_status: accepted

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

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)
• COLORPALETTE = tab10** — Default matplotlib color cycle. Options: tab10, Set2, colorblind (deuteranopia-safe)
• FONTSIZE = 10** — Base font size (matches typical conference body text)
• FIGDIR = figures/** — Output directory for generated figures
• REVIEWERMODEL = claude-review — Claude reviewer invoked through the local claude-review MCP bridge. Set CLAUDEREVIEW_MODEL if you need a specific Claude model override.

Inputs

1. PAPERPLAN.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:

| 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:

# 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):

Step 4: Generate Each Figure

For each figure in the plan, create a standalone Python script:

Line plots (training curves, scaling):

# 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):

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):

\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

# Run all figure generation scripts
for script in gen_fig*.py; do
    python "$script"
done

Verify all output files exist and are non-empty. Then render-then-verify: re-open each RENDERED PDF/PNG (not the script) and self-check — no clipped labels, no legend covering data, every number/label readable at final print size. This self-check happens BEFORE the Step 7 review, so the reviewer's budget goes to substance, not to catching clipped axes.

Step 6: Generate LaTeX Include Snippets

For each figure, output the LaTeX code to include it:

% === 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 Claude for review:

mcp__claude-review__review_start:
  prompt: |
    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]

After this start call, immediately save the returned jobId and poll mcpclaude-reviewreview_status with a bounded waitSeconds until done=true. Treat the completed status payload's response as the reviewer output, and save the completed threadId for any follow-up round.

Step 8: Quality Checklist

The checklist is PARTITIONED (pattern from Anthropic's Claude Science figure-style skill, Apache-2.0): correctness rules always bind — they are about whether the figure tells the truth, have no aesthetic content, and no style choice may override them; guidance rules are defaults — they produce a clean result, but a deliberate, stated alternative may override them.

Correctness — always binds, verify against the DATA before the render:

source either disappears entirely or is drawn visibly distinct (open / hatched marker, named in the key); it never feeds a mean/CI plotted alongside included rows

• [ ] Excluded data never enters summaries — a row excluded/flagged in the

row** — if one category contradicts the claim, qualify it ("on 3 of 4 benchmarks") or downgrade to a description; a figure that overclaims is wrong even if it renders beautifully

• [ ] **Captions and any claim-like title text are tested against EVERY plotted

/ protocol are not drawn as visual peers; separate them or mark the difference in the caption

• [ ] Comparable conditions only — arms measured under different N / budget

says n and the unit of replication (panel or caption)

• [ ] State n and what was held fixed — every panel with a summary mark

(not the script) actually happened: no clipped labels, no legend covering data, every number/label readable at final print size

• [ ] Render-then-verify — the Step-5 self-check on the RENDERED PDF/PNG

Guidance — strong defaults (from pedrohcgs/claude-code-my-workflow), a deliberate stated alternative may override — EXCEPT items that Key Rules below make hard (vector-PDF output and no-titles-inside-figures are Key Rules: treat those two as binding, not overridable):