/paper-figure-generate

name: paper-figure-generate
description: 'Generates publication-quality figures and diagrams from output/PAPER_PLAN.md for GIScience, GeoAI, and remote sensing journals (IJGIS, ISPRS JPRS, RSE, TGIS). Decides per-figure whether to produce reproducible code-generated plots/maps or structured prompts for external image-generation models (nano banana, ChatGPT image). Produces figure files, source scripts, captions, manifest, and prompt artifacts. Never fabricates results — uses only evidence from project files.'
argument-hint: [figure-number-or-"all"-or-plan-path]
allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, Agent, WebSearch, WebFetch, mcp__codex__codex, mcp__codex__codex-reply

Skill: paper-figure-generate

You turn the figure plan in **`output/PAPER_PLAN.md`** into manuscript-ready figures for **$ARGUMENTS**. For each figure you decide between a **code-generated** artifact (plots, maps, quantitative panels) and a **prompt-generated** artifact (workflow, architecture, conceptual diagrams) and produce the right deliverable with captions and provenance.

This skill is used when the manuscript needs:

• standard plots for spatial data science studies,
• a heterogeneous mix of figure types (maps + architecture + ablations + graphical abstract),
• diagrams better produced by an external image model,
• figure planning artifacts while some experiments are still in flight.

---

Constants

• **PLAN_PATH = `output/PAPER_PLAN.md`** — source of truth for figure inventory.
• **FIG_DIR = `output/figures/`** — all figure artifacts.
• **SCRIPT_DIR = `output/figures/scripts/`** — reproducible figure source code.
• **PROMPT_DIR = `output/figures/prompts/`** — external-image-model prompts and design notes.
• **MANIFEST = `output/figures/FIGURE_MANIFEST.md`** — master index of all figures.
• **CAPTIONS = `output/figures/FIGURE_CAPTIONS.md`** — manuscript-ready captions.
• **TARGET_VENUE** — read from `output/PAPER_PLAN.md` header, else `research_contract.md`, else default `IJGIS`.
• **EXPORT_FORMATS = `png, pdf`** — default raster + vector. Add `svg` if diagram will be edited by hand.
• **DPI = 300** — for raster exports.
• **FIG_WIDTH_SINGLE = 3.5in / 89mm** — single-column.
• **FIG_WIDTH_DOUBLE = 7.2in / 183mm** — double-column.

Override via argument (e.g., `/paper-figure-generate Fig03 — venue: ISPRS, formats: png,pdf,svg`).

---

Core Philosophy

1. **Evidence over aesthetics.** Never invent metrics, coordinates, or labels. If the evidence is not in the project files, produce a *specification stub* and stop — do not fill with plausible-looking data. 2. **Two honest pathways.** Every figure is either reproducible (code + data → image) or schematic (prompt → image). Pick one deliberately per figure; justify in the manifest. 3. **Publication discipline.** Restrained typography, consistent palette, legible at print size, grayscale-readable where feasible. No marketing gloss. 4. **Consistency across the paper.** Same fonts, line widths, terminology, dataset names, and notation as the manuscript. 5. **Graceful degradation.** Missing data → stub + TODO; partial system knowledge → draft prompt + assumptions list. Never silent guesses.

---

Phase 1 — Read and Interpret `PAPER_PLAN.md`

1. Read `output/PAPER_PLAN.md` fully. Locate:

• the **Figure Plan** table (IDs, types, priorities),
• the **Hero Figure** description,
• the **Claims-Evidence Matrix** / `memory/APPROVED_CLAIMS.md`,
• Methods and Results sections that reference specific figures/tables,
• any figure draft notes, mockups, or placeholder captions.

2. Resolve the target venue from the plan header (e.g., `Target: IJGIS`). Apply venue norms (column width, grayscale-safe palette, line-figure vs. color policy). 3. Build an **internal figure registry**. For each figure extract:

| Field | Notes | |---|---| | `id` | `Fig01`, `Fig02`, … — zero-padded. | | `title` | Short, manuscript-ready. | | `purpose` | Scientific message, one sentence. | | `key_message` | What a skim reader should take away. | | `claim_refs` | IDs from `APPROVED_CLAIMS.md` (if any). | | `data_source` | Path(s) or `MISSING`. | | `figure_type` | From the taxonomy below. | | `pathway` | `code` or `prompt` (Phase 3). | | `priority` | HIGH / MEDIUM / LOW from plan. | | `status` | `ready` / `stub` / `draft-prompt` / `blocked`. | | `annotations` | Labels, arrows, callouts required. | | `dependencies` | Tables, experiments, scripts it depends on. |

Persist this registry inline in the manifest (Phase 6). Do **not** write it to a separate JSON unless the user asks.

4. If `PAPER_PLAN.md` is missing or incomplete, attempt in order:

• read linked result files (`output/results/`, `output/spatial-analysis/`, `output/reports/`),
• read `memory/APPROVED_CLAIMS.md` + `memory/OUTLINE.md`,
• infer the smallest defensible figure set, and mark every inferred row with `assumption: inferred from <source>` in the manifest.

---

Phase 2 — Figure Type Taxonomy

Choose the type that best serves the scientific message, not the one that looks nicest.

| Family | Types | |---|---| | **Maps** | study-area map, choropleth, spatial distribution, bivariate map, hot-spot (LISA/Gi\*), error/residual map, change map, inset panels. | | **Quantitative plots** | bar, grouped bar, line, scatter, scatter-with-fit, box, violin, ECDF, heatmap, confusion matrix, calibration plot. | | **Ablation / sensitivity** | ablation bars with reference line, sensitivity heatmap, tornado plot. | | **Remote sensing panels** | multi-band image grid, before/after, multi-temporal stack, ground-truth vs. prediction panel. | | **Qualitative case studies** | image+label panels, attention/overlay visualizations. | | **Diagrams (prompt-friendly)** | system architecture, workflow/pipeline, conceptual framework, module interaction, graphical abstract, layered platform schematic, human-in-the-loop diagram, data-engine-model-output pipeline. |

**Map defaul