Sci Plot

SciPlot

Treat a scientific figure as an auditable visual argument:

question or claim → evidence → panel roles → visual encoding → rendered artifact

Optimize scientific fidelity and reader reasoning before aesthetics. Do not imitate a reference image at the expense of the data-generating process, analysis unit, uncertainty, or claim.

Treat “Nature-style” as a request for restrained, evidence-led publication design, not as an official affiliation or a universal visual preset.

Route the task

Classify the request before acting:

• Create: design and render a new figure from data, results, or a scientific question.
• Adapt: reproduce or adapt a reference figure, case, or visual system to new

data only after its scientific semantics pass the compatibility gate.

• Revise: change an existing figure, script, or layout while preserving all scientific meanings outside the requested change.
• Review: inspect figures, code, data mappings, or exports. Remain read-only unless the user also asks for implementation.
• Export: validate or convert existing figure artifacts without silently

changing their visual or scientific meaning.

For open-ended exploration, record an exploratory question instead of inventing a confirmatory claim. Produce candidate views and label them exploratory.

For a small cosmetic revision, use a minimal contract and avoid redesigning unrelated parts. For a structural revision, treat the task as Create while preserving a before/after change ledger.

Follow the core workflow

1. Inspect inputs

• Inventory data, code, existing figures, captions, analysis outputs, requested formats, and available runtimes.
• Identify what is observed, computed, inferred, or still unknown.
• Never infer units, replicate units, uncertainty definitions, or test meanings from appearance alone.

1. Establish the Figure Contract

• Read [figure-contract.md](references/figure-contract.md).
• Write the smallest contract appropriate to the route before choosing a layout.
• Ask only questions that block a scientifically valid result; mark non-blocking gaps as unknown and disclose them.
• Set the execution state to proceed, prototype-only, or blocked.

Never produce a production figure while a blocking scientific unknown remains.

1. Design the evidence architecture

• Read [figure-grammar.md](references/figure-grammar.md) for the case-independent design path.
• Assign every panel one question and one evidence role: primary, supporting, control, diagnostic, or context.
• Link every stated claim to its supporting panels. Remove panels that add no unique evidence or necessary orientation.
• Select encodings from the data structure and inferential goal, not from visual novelty.

1. Optionally use cases semantically

• Treat cases as design priors, not dependencies. Complete the evidence

architecture and resolve the relevant semantic hard constraints first.

• Read [case-index.md](references/case-index.md) first; do not load the full case library.
• Read [case-selection.md](references/case-selection.md) when matching a case or deciding the reuse level.
• Load only the selected entries from [cases-core.md](references/cases-core.md) or [cases-extensions.md](references/cases-extensions.md).
• Read [risk-cards.md](references/risk-cards.md) when reviewing a figure or when a planned encoding has a known failure mode.
• Permit an explicit no-suitable-case outcome. Record build-new and

continue through implementation; never stop merely because the library has no match.

• If source code would help, read [case-code.md](references/case-code.md).

Keep the semantic card, reference source, and verified implementation as separate layers.

• For production, prefer a semantically compatible verified native

implementation. Inspect a reference source pack when no native implementation matches or the user explicitly requests a faithful reconstruction; source availability never overrides semantic fit.

1. Protect data and statistical meaning

• Read [data-integrity.md](references/data-integrity.md) whenever the task involves filtering, missing values, transformations, aggregation, sampling, repeated measures, uncertainty, or statistical annotations.
• Preserve all requested observations by default.
• Record every exclusion, transformation, aggregation, and preview sample with its rule and before/after count.
• Keep demo data separate from production data. Never replace missing results with invented values.
• Do not silently recompute or change the user's analysis during a visual revision.

1. Implement and export

• Read [backends-and-export.md](references/backends-and-export.md) after the contract fixes the output requirements.
• Read [implementation-catalog.md](references/implementation-catalog.md)

when the provisional contract contains enough fields to judge compatibility. While blocked, catalog inspection may remain read-only, but implementation selection and execution must wait.

• Choose Python, R, or a documented mixed workflow per task; do not persist a global backend preference.
• Use one declared owner for final multi-panel assembly and retain panel-level provenance.
• Treat bundled case code as inspectable reference source, not as a

production template. Use scripts/stage_case.py to copy one selected backend into a new task directory; never edit or execute it in place.

• Exact or structural reuse requires a completed field/unit/replicate/

uncertainty mapping and every relevant transformation guard. Style-only reuse must not execute the case's statistical logic.

• Use generated demo inputs only for smoke tests. Never place demo values in

a production figure or Render Manifest.

• Prefer editable text and vector geometry; rasterize only dense marks or inherently raster data.
• Treat implementation defaults for height, DPI, order, and palette as

disclosed proposals only. Confirm or derive them in the Figure Contract before production rendering.

1. Render and verify

• Read [qa.md](references/qa.md) before declaring completion.
• Run the actual code, open the actual artifacts, and inspect them at the intended physical size.
• Verify statistical semantics, data-to-mark traceability, accessibility, clipping, typography, panel alignment, dimensions, fonts, and file integrity.
• Distinguish code lint, runtime success, artifact validity, visual quality, and scientific validity; none proves the others.
• Iterate render → inspect → fix → rerender until no production-blocking

failure remains.

Use scripts/rank_cases.py only to retrieve candidates after scientific hard constraints are known. Use scripts/validate_contract.py to lint a serialized Figure Contract. Use scripts/validate_delivery.py to reconcile its declared formats, dimensions, DPI, hash, and included outputs with the actual Render Manifest. Use scripts/inspect_artifacts.py on rendered files and scripts/build_qa_report.py to assemble the machine-readable delivery report. For Revise or Adapt, use scripts/semantic_diff.py to detect changes to locked scientific meanings. Use scripts/stage_case.py to inspect or stage a selected reference source pack and scripts/generate_case_demo.py only for supported synthetic smoke tests. Use scripts/validate_implementations.py before running a bundled native implementation; its presence never overrides the semantic gate. These tools make deterministic checks; none replaces scientific or final-size visual judgment. Script paths in this skill are relative to the installed sci-plot directory. From this repository root, prefix them with skills/sci-plot/.

Maintain four auditable records

Keep these concepts distinct even when a simple task combines them in one compact file. Read [audit-records.md](references/audit-records.md) when implementing, revising, or delivering a production figure:

1. Figure Contract — scientific question, claims, analysis units,

statistical meanings, constraints, and unresolved risks.

1. Figure Plan — evidence atoms, panel roles, visual encodings, reading

order, and case influence.

1. Render Manifest — backend, entrypoint, inputs, environment, dimensions,

outputs, and hashes for each panel and final assembly.

1. QA Report — stable check IDs, evidence, artifact measurements,

unresolved warnings, and final readiness.

Preserve these invariants

• Keep the scientific question, analysis unit, and replicate unit explicit.
• Make n, denominator, units, center, uncertainty, test, and multiplicity correction unambiguous wherever they affect interpretation.
• Do not hide inconvenient points, missingness, null results, or long tails for visual neatness.
• Do not use color, area, length, ordering, smoothing, or axis limits in ways that exaggerate evidence.
• Default bars and filled areas to a meaningful zero baseline; disclose any justified exception.
• Separate descriptive, associational, predictive, and causal claims.
• Keep precomputed coordinates or statistics labeled as such; do not imply they were recomputed.
• Preserve user-owned work and avoid unrelated file changes.

Reuse a case at the right level

Choose exactly one:

1. Exact reuse — same scientific semantics, dimensions, transformations, and compatible input schema.
2. Structural adaptation — same evidence logic with an explicit field, unit, category-order, and replicate mapping.
3. Style-only inheritance — borrow visual tokens or annotation grammar, not statistical logic.
4. Build anew — use when the scientific question, data structure, or inferential assumptions differ.

The user's data and Figure Contract remain authoritative at every level.

Deliver by route

For Create, Adapt, or Revise, deliver:

• runnable source code and any explicit configuration;
• an editable primary artifact when feasible, plus a review preview;
• the completed or updated Figure Contract;
• a concise record of exclusions, transformations, statistics, case influence, and backend provenance;
• QA results and unresolved limitations.

For Review, deliver:

• the inferred claim/evidence map, including confidence and unknowns;
• issues grouped by scientific meaning, data integrity, statistical semantics, visual communication, reproducibility, and export;
• severity, evidence, and a scoped remedy for each actionable issue;
• no file changes unless separately authorized.

For Export, deliver the converted or validated artifacts, measured output properties, provenance of any conversion, and a QA report. Do not claim scientific validation when only file-level checks were possible.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SciToolsmith
• Source: SciToolsmith/sci-plot
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.