mathmod-figure

name	mathmod-figure
description	Claim-first figure task Skill for mathematical-modeling competitions. Use it to decide whether a figure deserves paper space, plan and render conceptual, quantitative, or hybrid figures from current semantic context and formal evidence, and review them at their real submission size. It is a focused M4 task skill, host-neutral, and does not create scientific facts or runtime state.

MathMod Figure

ROLE

Use this focused M4 task skill for figures that explain a competition model or present its checked results. It covers figure triage, planning, source/data mapping, rendering, refinement, and visual QA. Any capable person, agent, or tool may perform the work; host choice is not part of the contract.

This is not M5. It is an M4 task skill used alongside mathmod-writing: figure work owns the figure claim, figure brief, rendering, and visual checks, while writing owns paper narrative, captions, placement, and delivery. It does not manage tasks, lifecycle, scheduling, claims, leases, or release authority, and it does not depend on .mathmod, MCP, or a host runtime.

READ PROGRESSIVELY

1. D0: project AGENTS.md and CONTEXT.md.
2. D1: the relevant sections of context/model.md, context/data.md, context/evidence.md, context/visuals.md, and context/paper.md; read a handoff only when this task needs it.
3. D2: for numeric content, follow current_run.json to the selected successful formal run, its findings, artifacts, and any render-ready data. Read source data or plotting code only as needed.
4. D3: use raw/history artifacts for conflict, provenance, or debugging—not as a way to guess current evidence.

A missing or contradictory semantic home is a stop-and-escalate condition for the affected figure. Do not infer a result from an old image when exact evidence is available.

WORK ORDER

0. Figure portfolio gate

Before designing anything, decide whether the visual deserves paper space.

Ask only:

1. Is a figure faster or clearer than one short paragraph or one compact table for the same claim?
2. Does it add inferential value rather than repeat an existing figure/table?
3. Should it live in the main text, appendix, or remain table/text only?

If a figure does not earn its footprint, do not force one. Existing artifacts are not a reason to duplicate them as paper figures.

1. Claim first

Before choosing a chart or layout, write a one-sentence figure claim with a verb. Map the claim to the smallest defensible evidence chain, identify the hero evidence, and give each panel a necessary role. Record what the figure supports and does not support. Remove a panel that adds no inferential value.

2. Submission layout first

Determine the actual delivery layout before drawing:

• competition or target format;
• page size and margin constraints;
• usable text width/height;
• intended placed width/height and main-text/appendix location;
• minimum readable text size at the placed size;
• required output formats.

Design at the size that will appear in the submitted paper. Do not inherit Nature-style or other journal-default widths when the competition layout differs, and do not rely on a large-screen preview to hide unreadable labels, crowded legends, weak contrast, or misleading cropping.

For ordinary competition figures, prefer an editable/vector master (SVG or PDF) plus a 300-dpi PNG review preview. Generate TIFF/EPS/high-DPI raster only when the target format actually requires it.

3. Apply the evidence gate

• A quantitative figure may use only values, units, groups, uncertainty, and ordering supplied by the current successful formal evidence and its render-ready exports.
• A hybrid figure marks conceptual and evidence-backed regions separately; its numeric region follows the quantitative rule.
• A conceptual figure may explain a model, workflow, mechanism, or dependency without numbers, but it must preserve the semantic relationship, direction, terminology, and claim strength in context/model.md.
• Probe, draft, inferred, or stale results are not formal evidence. Missing evidence is a gap to return to compute, not an invitation to estimate.

Figure work may perform render-aware profiling of render-ready data—series/category counts, missingness, numeric span, label density, and uncertainty columns—to choose a clear encoding. It must not redefine exclusions, grouping, transforms, smoothing, aggregation, uncertainty, or statistical meaning. Those decisions return to compute or reasoning.

4. Select the visual route

• Quantitative: use deterministic plotting. Do not use image generation for axes, scales, exact values, tables, confusion matrices, equations, or formal evidence panels.
• Conceptual: deterministic diagramming or image generation may be used. Generated imagery is illustrative and must not invent quantitative facts, exact topology, equations, or supported claims.
• Hybrid: keep evidence-bearing quantitative regions deterministic. A generated conceptual companion panel must remain clearly illustrative and visually separable.

If exact formulas, exact numeric labels, or evidence-bearing geometry matter, prefer editable deterministic tools such as Matplotlib, Graphviz, Draw.io, or TikZ.

5. Build

Choose the minimum suitable archetype and visual family. Keep condition/model encodings consistent across related figures and preserve an editable/source form when practical. Use the references below only when the current task needs their detail.

6. Rendered review loop

Inspect the rendered figure at its real placed size. For each round:

1. render a placed-size preview;
2. first enumerate what is actually visible—panels, axes, scales, legends, annotations, uncertainty, and data marks;
3. then judge scientific fidelity, visual hierarchy, readability, scale honesty, clipping, overlaps, annotation/data collisions, fonts, grayscale/color accessibility, and whether the claim is apparent quickly;
4. fix and rerender.

Use at most three ordinary repair rounds. If the structure is still weak, redesign the figure instead of polishing the same layout indefinitely. If scientific meaning changes, return to reasoning/compute.

Machine audits are risk-triggered diagnostics, not a universal release gate; see references/qa.md.

WRITE BACK

• Figure purpose, claim, type, source, use location, Must preserve, and May change → context/visuals.md.
• Render-ready inputs and figure source/output → visuals/.
• Figure legend, caption, placement, and final document fit → paper/ through the writing contract.
• Missing evidence, semantic conflict, or a changed claim → return to compute/reasoning in a short ordinary handoff; do not repair it through styling.

Before stopping, reconcile CONTEXT.md and context/visuals.md: remove completed figure work from the current focus and confirm the recorded QA/status matches the rendered artifacts.

Use this compact brief:

Purpose / figure-level claim:
Placement: main | appendix | table/text instead
Type: conceptual | quantitative | hybrid
Submission layout / placed size / output:
Panel map and hero evidence:
Data/source paths:
Formal evidence source (if numeric):
Must preserve:
May change:
Supported / unsupported claim:
QA completed / remaining:

ROUTES

• Submission-size design language and visual consistency → design system
• Choosing conceptual/quantitative/hybrid structure and a math-modeling visual family → archetypes
• Evidence, rendered review, and triggered machine QA → QA
• Conceptual image-generation route and boundaries → image generation workflow
• Independent inspiration and attribution → inspiration

Do not add a figure registry, .mathmod files, MCP configuration, scheduler, claim/lease state, backend state machine, mandatory figure count, or a second evidence system for ordinary figure work.