---
name: figure-tool
description: Generate research figures — structural SVG (architecture / pipeline / concept) or data matplotlib plots — plus curate a reference-figure library. Each figure goes through a 6-step interactive flow (intent → kind → refs → size → palette → render) and lands in the correct paper or experiment scope. Triggered by /figure.
---

# figure-tool

> **Source spec:** `docs/superpowers/specs/2026-05-13-figure-tool-design.md`. Read it before
> the first invocation in any session.
>
> **Required style prelude:** also read
> `.claude/skills/paper-architect/references/latex-conventions.md` sections
> `hard-rules` (no `;`, no `---`/`--`) and `tables-and-figures` (vector PDF,
> grayscale-resilient, ≤6 colors, arrow flow, font size between body and
> caption, caption answers "what is this"). The rules apply to figure
> captions, axis labels, legend text, and any text label inside a structural
> SVG.

## Mental model

A figure is one of two **kinds** (structural / data) under one of two **scopes** (paper / experiment).

```
                       /figure new <slug>
                              │
              ┌───────────────┴───────────────┐
        scope=paper                    scope=experiment
              │                                │
   outputs/papers/<v>/<d>/         outputs/experiments/<exp>/repo/
   figures/<slug>.{svg,pdf,png}    figures/<vN.M>/<slug>.{svg,pdf,png}   (data)
                                   figures/_arch/<slug>.{svg,pdf,png}    (structural)
```

Reference figures (style inspiration) are global:
`inputs/figure-refs/<slug>/{image, note.md}` + AgentDB
`project/figure-refs/<slug>`.

## Evidence-first & QA (always applies)

Same anti-fabrication spine as `/paper write` / `/paper verify`, applied to
figures. Adapted from the *academic-figure* skill of
[joshua-zyy/academic-paper-writer](https://github.com/joshua-zyy/academic-paper-writer).

**Never fabricate.** A figure serves a claim — it is never ornament.
- **Data plots:** plot only user-provided experiment data or already-verified
  numbers. Never synthesise plausible-looking points to fill a curve. If the
  data isn't on hand, stop and tell the user which file/metric is missing
  rather than inventing it (mirrors the `[DATA_NEEDED]` discipline in prose).
- **Architecture / structural diagrams:** draw only modules, connections, and
  data flows that the actual code (at the bound repo SHA) or the paper supports.
  Don't invent a block or an arrow to make the diagram look complete. Mark any
  element you can't confirm with a literal `[VERIFY_ARCH: <what's unconfirmed>]`
  text node in the SVG and list it in the note's body — the user resolves it
  before the figure ships, exactly like a prose placeholder.

**Data-plot QA checklist** (verify before declaring a data figure done):
1. No rainbow / jet colormap — use the resolved academic palette only.
2. A truncated axis (non-zero origin) is explicitly marked / annotated.
3. Error bars / bands state their type in the caption (std / SEM / 95% CI).
4. Series are distinguishable in grayscale — never hue alone (pair with dash /
   marker), per the existing `latex-conventions.md` rule.
5. Panel labels (a/b/c) and the caption serve the figure's claim.

Surface this checklist's result in the `/figure new` data-path output so the
user sees it was applied.

## Cursor reads (always do this first)

At every `/figure ...` invocation, read both cursors:

* `mcp__claude-flow__memory_retrieve` namespace=`project`, key=`paper-context.current`
  → expect `{"venue": "...", "direction": "..."}` or absent
* `mcp__claude-flow__memory_retrieve` namespace=`project`, key=`experiment-context.current`
  → expect `{"slug": "..."}` or absent

Call `research_assistant.figures.paths.resolve_scope(paper_ctx=..., experiment_ctx=..., cli_scope=...)` (all three args are keyword-only):

* `NoScopeError` → tell the user to run `/paper venue` or `/experiment init`.
* `AmbiguousScopeError` → ask "paper or experiment?" (step 0).

## Subcommand router

| Subcommand | Action |
|---|---|
| `new <slug>` | Run the 6-step interactive flow (below). |
| `recommend` | Suggest the right academic chart type from a pasted data snippet + one-sentence intent. Reads `references/chart-recommender-prompt.md` (19-chart library) and prints a structured recommendation; hands off to `/figure new <slug>` for actual generation. |
| `list` (default) | `ls figures/*.pdf` under current scope; render a table with slug + kind + size + created. |
| `render <slug>` | `figures.export.export(svg_path)`. If the source is a matplotlib script, exec it instead. |
| `render --all` | walk current scope's `figures/**/*.svg` and `**/plot_*.py`; export each. Summary table at end. |
| `edit <slug>` | Print the absolute path of `<slug>.svg`. Do NOT modify. User opens in Inkscape. |
| `export <slug> --format jpeg --quality 90` | Re-render PNG, convert to JPEG (Pillow). Skip if user didn't pass `--format`. |
| `ref add [<file>\|--url <u>]` | See "Reference intake" below. |
| `ref list [--kind k] [--tag t]` | Read `research_assistant.figures.refs.list_refs()`, parse each via `read_ref(slug)`, filter, table. |
| `ref sync` | Walk `inputs/figure-refs/*/note.md`; for each, `to_agentdb_payload(ref)` → `mcp__claude-flow__memory_store`. |
| `ref show <slug>` | Print note.md + absolute image path. |

## `/figure recommend` flow

A read-only decision-support subcommand. Does not write any file; prints a
recommendation and surfaces the natural next call (`/figure new <slug>`).

1. Resolve scope (cursor reads above) — needed only for the palette hint in
   the recommendation. Do **not** error on `NoScopeError`; the recommender
   is useful even before a paper or experiment exists.
2. Collect inputs (plain text, no `AskUserQuestion` per the
   `feedback_decision_ui` memory):
   - **Data snippet** — paste an Excel/CSV table, or a 2–3 line description
     of variables, axes, sample count, distribution shape.
   - **Core conclusion** — one sentence on what the figure must demonstrate.
3. Read `references/chart-recommender-prompt.md` as the prompt prelude
   (it embeds the 19-chart academic library verbatim).
4. Apply the prompt with the stitched `# Input` block.
5. Print the model's four-section response (推荐方案 · 核心理由 · 视觉设计
   规范) and the hand-off line: `Next: /figure new <slug>  (kind=data,
   chart=<推荐>)`.

## `/figure new` 6-step flow

**Collision guard (before Step 1).** After scope is resolved, check whether the
target figures dir already holds `<slug>.note.md` (or `<slug>.svg` / `plot_<slug>.py`).
If so and the user did **not** pass `--force`, refuse with
`figure '<slug>' already exists in <scope> — pass --force to overwrite` and stop
(matches the Error-policy row). With `--force`, proceed and overwrite. Without
this guard the render steps silently overwrite an existing figure.

**Step 0 — scope** (only if `AmbiguousScopeError`)
Ask in plain text (per memory rule on multi-option research picks): "Paper or experiment?" — accept `paper` / `experiment`. Persist only to this invocation.

**Step 1 — intent**
Ask: "这张图要让读者一秒看懂什么？" — one sentence. Store as the future `intent:` frontmatter.

**Step 2 — kind**
Ask: "structural 还是 data?" — accept `structural` / `data`. If `data`, also ask which experiment version (defaults to the latest if scope=experiment).

**Step 3 — references**
1. Build a query from `{intent} {kind}` + intent-extracted keywords.
2. Call `mcp__claude-flow__memory_search` namespace=`project/figure-refs`, query, topK=5.
3. Show up to 3 candidates as: `[N] <slug>  tags: ...  palette: <ANSI swatches>  why: <first line of why_i_like_it>`.
4. If the library is empty, skip silently. In any case, also accept inline paths/URLs (`+ <path>` or `+ <url>`).
5. Record the selected slugs for the future `refs:` field.

**Step 4 — size**
Read venue's `_venue.md` (if it exists at `outputs/papers/<v>/_venue.md`) for column widths. Offer 4 options:

```
[1] single-column         (3.3 in × auto)
[2] double-column-half    (6.5 in × 3.0 in)
[3] double-column-full    (7.0 in × auto)
[4] custom                (you type W H in inches)
```

**Step 5 — palette**
1. Resolve via `palette.load_palette_for_direction(figures_dir, fallback=<venue-recommended>)`.
2. If the direction has `_palette.yml`, default = that palette; also offer 2 alternatives from shipped (`paper-trio`, `paper-extended`).
3. Else, offer 3 shipped palettes filtered by `kind` and `size` (heuristics: single-column → mono/trio first; multi-line ablation → extended; poster/slides → dark-on-light).
4. Render each option with `palette.ansi_swatch(spec)`.

**Step 6 — render**

For **kind=structural**:
1. Construct the prompt for SVG generation, including:
   - Inkscape conventions from spec section 5.1 (viewBox in 96 DPI inches, namespace, labelled layers, `<defs>`-centralised styles).
   - Selected refs as multimodal image inputs.
   - The palette's hex colors and slot names.
   - The intent sentence.
   - **Project conventions** (from `latex-conventions.md` section `tables-and-figures`):
     vector-only (no raster embeds), grayscale-resilient (test by removing
     color — lines stay distinguishable by dash pattern, marker shape, or
     position), ≤6 colors total consistent within functional modules (same
     color means the same role across all figures in the paper), arrows flow
     in one general direction (left-to-right or top-to-bottom), prefer visual
     encodings over text labels for repeated information, figure text size
     between body and caption (typically 7–8 pt in two-column).
   - **Architecture-diagram style** (from `references/architecture-diagram-prompt.md`):
     flat-vector aesthetic in the DeepMind / OpenAI mold — pure-white
     background, soft palette, simple icons, English-only text labels, no
     long sentences inside boxes, no 3D shadows / sketch lines / photo-realism.
     This prelude carries the visual-style guidance adapted from the
     [awesome-ai-research-writing](https://github.com/Leey21/awesome-ai-research-writing)
     "论文架构图" entry; reproduce the Visual Constraints block verbatim
     when constructing the prompt.
   - **Hard rules** for any text inside the SVG (labels, legends,
     annotations): no `;` as punctuation, no `---` or `--` as prose
     punctuation. Restructure with commas or split labels.
   - **Evidence-first** (see "Evidence-first & QA" above): draw only
     code/paper-supported modules and flows; mark anything unconfirmed as a
     `[VERIFY_ARCH: …]` text node and record it in the note body — never
     invent structure to look complete.
2. Decide D2 scaffold opt-in: if structure is genuinely auto-layout (boxes + arrows), generate a `.d2` source first, call `d2.scaffold_to_svg(...)`. If it returns `None`, fall back to raw SVG generation. If success, set `backend: d2-scaffolded`; otherwise `backend: raw-svg`.
3. Write `<slug>.svg` to the resolved figures dir.
4. Call `figures.export.export(svg_path)`. On `ExportError`, leave the SVG and tell the user to inspect.
5. Write `<slug>.note.md` via `figures.note.write_note(note_path, FigureNote(...), body="")`.
6. If `scope == "experiment"`, call `research_assistant.experiments.append_figures_to_version(slug=<exp-slug>, version=<vN.M>, figure_stems=["repo/figures/_arch/<slug>"])`. Structural figures are **non-versioned** — they live under `repo/figures/_arch/` (see `experiment_figures_dir(slug, version=None)`), so the link-back stem must use `_arch/`, not `<vN.M>/` (that form is only correct for the data branch).
7. Print the LaTeX include snippet (see "Insert snippet" below).

For **kind=data**:
0. **Trajectory shortcut.** If the intent contains "trajectory", "training
   curve", "metric over runs", or similar, and either (a) the user said
   "send to chat / paste into HTML" or (b) `matplotlib` is unavailable,
   reach for `references/trajectory-svg-recipe.md` *instead of* matplotlib.
   That recipe is a zero-dependency pure-Python SVG (~80 lines, adapted
   from Orchestra-Research/AI-Research-SKILLs MIT
   `0-autoresearch-skill`). Write `plot_<slug>.svg.py` (driver) +
   `<slug>.svg` next to it; skip the `cairosvg` / mplstyle path; set
   `backend: trajectory-svg` in the note. For all other "metric over
   time" plots, fall through to the matplotlib path below.
1. Write `plot_<slug>.py` to the scripts dir for this scope:
   - paper: `outputs/papers/<v>/<d>/figures/_scripts/plot_<slug>.py`
   - experiment: `outputs/experiments/<exp>/repo/scripts/plot_<slug>.py`
2. Script header includes a docstring with data source (path / columns / metric) confirmed in Step 1+3.
3. Script imports `from research_assistant.figures.save import save_all` and uses `matplotlib.style.use(<absolute-path-to-mplstyle>)` for the chosen palette. `save_all` writes **`.pdf` + `.png`** (no `.svg` — for data figures the script itself is the canonical source).
3a. **Project conventions** (from `latex-conventions.md` section `tables-and-figures`):
   - Axis labels, legend entries, and tick labels obey hard rules: no `;`, no
     `---`/`--`.
   - Math inside labels uses built-in operators (`\arg\max`, `\log`) and
     `\textrm{}` for multi-letter names (`\textrm{softmax}`).
   - Use the resolved palette's colors and the palette mplstyle; do not
     hardcode hex.
   - Limit visible series to ≤6 and design for grayscale: pair each color
     with a distinct marker or dash pattern so the figure survives black-and-
     white printing.
4. Jupyter-friendly: if the user prefers to iterate in a notebook, develop in Jupyter and export to `.py` via `jupytext --to py <name>.ipynb` or `File → Save As → .py`. The committed `plot_<slug>.py` stays the source of truth; the figure-tool does not generate `.ipynb` files.
5. Execute the script (Bash: `python <path-to-plot-script>`). Pipe output; if non-zero exit, surface stderr.
   **Evidence-first:** the script must read real data (a CSV/TSV path or values
   the user confirmed in Step 1+3). Never hardcode invented numbers to produce
   a nice-looking curve — if the data isn't available, stop and name the
   missing file/metric.
6. Run the **data-plot QA checklist** ("Evidence-first & QA" above): palette
   (no rainbow/jet), axis-truncation marked, error-bar type stated, grayscale-
   distinguishable, labels serve the claim. Note any item that fails.
7. Write `<slug>.note.md` via `write_note(...)` with `backend: matplotlib`.
8. Experiment scope: same `append_figures_to_version` link-back as structural.
9. Print the LaTeX include snippet, followed by a one-line QA summary
   (`QA: palette ✓ · axis ✓ · error-bars n/a · grayscale ✓`).

## Insert snippet

After every successful `/figure new` and `/figure render`, print exactly:

```
✓ Files: <abs-path>.svg / .pdf / .png
✓ Note:  <abs-path>.note.md
✓ LaTeX include (copy into your .tex):

    \begin{figure}[t]
      \centering
      \includegraphics[width={WIDTH}]{figures/<slug>.pdf}
      \caption{<intent>}
      \label{fig:<slug>}
    \end{figure}
```

`{WIDTH}` from `size.preset`:
* `single-column` → `\columnwidth`
* `double-column-half` → `0.48\textwidth`
* `double-column-full` → `\textwidth`
* `custom` → `\columnwidth` (let user adjust)

For **experiment scope**, the include path is `repo/figures/<vN.M>/<slug>.pdf` instead.

**Caption rules** (apply when the user pastes the snippet into their `.tex`,
and again when `/paper write` drafts the surrounding section):
* The caption answers *what is this*. Let the body text answer *what does it
  mean*.
* Hard rules: no `;`, no `---` or `--`. Restructure with commas or split into
  two sentences.
* Quantify any claim that the figure shows a `good` or `better` result. State
  the metric and the magnitude.
* Define every acronym in the caption on first use within the caption.
* **Format rules** (from `paper-architect/references/latex-conventions.md`
  section `tables-and-figures` → "Caption format"): decide case by syntax —
  noun phrase = Title Case, no period; complete sentence = Sentence case,
  end with period. Don't open with `The figure shows ...` / `This diagram
  illustrates ...`. Don't use `showcase` / `depict`. No `Figure 1:` prefix
  in the source.
* **Chinese intent → English caption.** Step 1 collects `intent:` as one
  Chinese sentence. When emitting the LaTeX snippet, **polish the intent to
  an English caption per the rules above** — do not paste the raw Chinese.
  Persist both: `intent:` in `note.md` stays Chinese (for future recall);
  the `\caption{...}` argument is the polished English.

## Reference intake — `/figure ref add`

1. Resolve the input image: positional `<file>`, `--url <u>` (curl into `inputs/figure-refs/staging/`), or scan `inputs/figure-refs/staging/`.
2. Ask: slug (default = kebab of filename).
3. Ask: source citation.
4. Ask: kind (`structural` / `data` / `mixed`).
5. Auto-suggest tags + why_i_like_it: read the image multimodally, propose 1 paragraph for `why_i_like_it` and a short list of `tags`. **Show the suggestion and ask the user to confirm / edit / replace**.
6. Auto-extract palette: `palette.extract_palette_from_image(image_path, count=6)`. Show; user may override.
7. Build a `FigureRef`, call `refs.add_ref(image_path, ref)`.
8. Call `mcp__claude-flow__memory_store` with `refs.to_agentdb_payload(ref)`.

## Error policy

| Failure | Behaviour |
|---|---|
| `NoScopeError` | Refuse with hint: `先 /paper venue 或 /experiment init` |
| `AmbiguousScopeError` | Ask step-0 "paper or experiment?" |
| Slug exists in target dir | Refuse; suggest `--force` |
| Path traversal | Reject at boundary (`paths.safe_join` raises) |
| `cairosvg` raises | Print error; SVG stays; pdf/png skipped |
| `d2` missing or fails | Auto-fall-back to raw SVG; one-line info |
| AgentDB unreachable (for `ref sync` / `ref add`) | Filesystem ops complete; warn once that index is stale |

## When NOT to use this skill

* Wrappers / packaging logic for camera-ready submissions — that belongs to `paper-architect` / `ref-manager`.
* Editing already-existing SVGs by hand — print the path with `/figure edit`; the user opens in Inkscape themselves.