figure-quality

name	figure-quality
description	Improve Research Harness manuscript figures and visual evidence. Use when a paper/PDF has low-quality figures, placeholder fbox/minipage diagrams, blurry PNGs, weak visual evidence, missing publication-ready graphics, figure/table quality review blockers, or requests to use Codex/ImageGen/GPT Image to generate academic paper figures.
public_suite	paper
task_type	visual-evaluation
data_access_level	local-files
inputs	figure_plan, manuscript, final_bundle, recorded result artifacts
outputs	publication-ready figure assets, figure provenance, visual-risk report
gates	result figures must use recorded evidence; generated assets need provenance
artifact_schemas	figure_plan, final_bundle_quality_report
estimated_runtime	20-90 min

Figure Quality

Use this skill to turn RH figure_plan artifacts and manuscript context into publication-ready figure assets. Prefer the current Codex session's built-in ImageGen capability when it is available; do not confuse that session tool with the RH Python primitive or Codex CLI.

For Nature/high-impact-journal style expectations, use the adapted guidance in references/nature-figure-adaptation.md. The goal is not decorative image generation; each figure should act as a visual argument with a clear claim, evidence boundary, panel logic, export contract, and review-risk check.

Decision Order

1. Inspect the manuscript TeX/PDF and latest RH figure_plan, publication_pack, final_bundle, and review artifacts.
2. Define a quick figure contract before generation: one-sentence claim, evidence boundary, panel map, archetype, asset route, export needs, and review risks. Load references/nature-figure-adaptation.md for multi-panel, Nature-style, or reviewer-facing figure work.
3. Classify existing figures:
   • placeholder: \fbox, minipage, ASCII arrows, text-only mockups.
   • low_quality_raster: blurry, low-resolution, screenshot-like, tiny labels.
   • acceptable_asset: readable publication graphic with clear provenance.
   • evidence_gap: figure is attractive but does not represent recorded evidence.
4. If the current assistant session exposes an ImageGen tool, call it directly for new bitmap figure assets when the figure is conceptual, schematic, protocol, evidence-lineage, or mixed-modality with no numeric chart source.
5. For quantitative charts, prefer deterministic Python/R/SVG/PDF generation from recorded data; do not invent numbers in ImageGen.
6. If ImageGen is not exposed, use deterministic SVG/TikZ/PDF diagrams for simple workflows, or use the RH figure_generate primitive/API path only when credentials are available.
7. Never claim that a figure was generated if the image tool or API was unavailable.

ImageGen Workflow

When using Codex ImageGen:

1. Build one prompt per figure from the RH figure_plan, manuscript section, caption, and evidence boundary.
2. Encode the figure contract in the prompt:
   • visual claim and panel role;
   • whether the figure is conceptual, planned, or evidence-backed;
   • requested archetype such as schematic-led composite or asymmetric mixed-modality;
   • required labels and forbidden labels.
3. Use academic-diagram prompts:
   • white background;
   • crisp vector-like layout;
   • short English labels, usually 2-4 words;
   • no tiny text, watermarks, logos, decorative gradients, or photorealistic effects;
   • restrained palette: neutral family, signal family, and at most one accent;
   • clear arrows, grouping, and hierarchy.
4. Prefer one hero panel plus subordinate evidence/process panels instead of equal-weight clutter when the figure has multiple concepts.
5. Generate wide landscape assets for paper diagrams unless the figure plan clearly needs another aspect ratio.
6. Copy generated files from the Codex generated-images directory into the relevant manuscript workspace; keep the original generated file in place.
7. Update the TeX to use \includegraphics for the new asset, preserving the evidence boundary in the caption.
8. Recompile or run the available PDF quality checks.
9. Record a durable RH state update or artifact that includes source figure plan id, generated asset path, prompt summary, figure contract, and any remaining visual limitations.

Evidence Rules

• Do not turn expected/planned results into observed results.
• Label planned-study diagrams as design or protocol figures, not empirical findings.
• For result figures, use only recorded numbers, tables, or artifacts.
• If generated text in the image is wrong or unreadable, regenerate or replace labels locally; do not ship unreadable labels.
• Prefer diagrams that explain system flow, study protocol, evidence lineage, or review blockers over decorative illustrations.
• Treat statistics, sample size, error definitions, source-data traceability, and image-integrity notes as part of figure readiness for evidence-backed result figures.

Quality Gate

Before calling a figure repaired, verify:

• every manuscript figure is either an acceptable asset or intentionally text/table-based;
• placeholder \fbox diagrams have been replaced or explicitly justified;
• labels are readable at final PDF scale;
• captions state whether the figure is conceptual, planned, or evidence-backed;
• image paths are local to the manuscript workspace or RH output bundle;
• result plots have source data or an explicit statement that they are conceptual/planned rather than empirical;
• compilation has no new LaTeX errors, undefined citations, or high-severity overfull boxes.

Boundaries

• Codex CLI supports attaching images as input; it does not provide a stable local codex image-generate command for RH Python code to call.
• The session ImageGen tool is an agent capability, not a reproducible RH primitive. Use RH artifacts to record what was generated and why.
• For automated non-interactive runs, use a programmable provider such as OpenAI Image API or deterministic SVG/TikZ; do not rely on hidden session-only tools.
• Do not import Nature plotting-backend gates blindly. When this skill uses Codex ImageGen, Python/R selection is not required; backend selection only matters for deterministic charts generated from data.

References

• references/nature-figure-adaptation.md — load for Nature-style figure contracts, archetypes, source-data/export expectations, QA checks, and chart-pattern routing.