figure-prompt-builder git:20261018.1d85de7A

Immutable. This exact content never changes and is served at /api/v1/blob/26c95241bc9cc6ed.

---
name: figure-prompt-builder
description: Build copy-ready prompts for explanatory figures such as overviews, architectures, mechanisms, workflows, timelines, and conceptual illustrations from source text, figure ideas, reference figures, or rough drafts. Use when Codex needs to decide whether a section needs an explanatory figure, distill the figure's core message and required visual elements, select a small number of structural or style donors from a reference bank, draft a model-neutral prompt pack for image-generation models, adapt prompts to a requested tool, or recommend limited cleanup after external generation.
---

# Figure Prompt Builder

## Overview

Use this skill when the user wants help with nontrivial figures beyond a simple
placeholder.

This skill is not limited to NSF proposals. Treat the surrounding task context
as the constraint:

- proposals
- papers
- slides
- posters
- reports
- technical docs
- websites or demos when the figure is the main artifact

This skill is mainly for explanatory figures rather than publication result
plots. Its strongest cases are:

- system or project overviews
- workflow and task pipelines
- local mechanism or subsystem diagrams
- method composites and scientific schematics
- timelines or work plans
- conceptual illustrations or theory cues

This skill is for prompt-building workflow, not for high-level writing framing:

- adjacent writing skills can decide whether a section needs a figure
- `figure-prompt-builder` turns that need into a concise figure brief,
  downstream prompt pack, and limited follow-up guidance

Use it when the user asks for work such as:

- what figure should support this intro or thrust
- create a figure brief, caption, and downstream prompt pack
- generate a model-neutral prompt for Gemini, Claude, ChatGPT image tools,
  Sora, Midjourney, Flux, or another outside tool
- adapt one prompt to a specific downstream model
- compare prompt strategies for different rendering models
- decide whether an outside model output needs reprompting, light cleanup, or
  can be accepted as final

Read these references only as needed:

- figure archetypes and example anchors: `references/figure-archetypes.md`
- bundled portable reference bank with structure and style donors:
  `references/reference-bank.md`
- larger repo-level figure archive when available locally:
  `../../figure-references/index.md`
- format and tool choice: `references/tool-selection.md`
- outside-tool prompt packs and import flow: `references/external-handoff.md`
- cross-model prompt design for image generation: `references/prompt-design.md`

In a multi-project repo, use `<work-dir>` to mean the concrete workspace for
the figure task, such as one proposal folder, one paper folder, or one slide
deck directory.

Use `scripts/init_figure_spec.py` when the user wants a concrete local figure
brief scaffold before writing the final prompt pack.

## Top design priority for Yue Zhao

For paper and proposal figures, understanding and imitating the author's confirmed preferences is required before drafting layout or prompt instructions. Resolve `editable-figure` through the normal skill lookup and follow `references/gallery/index.md#required-preference-first-design`: inspect the selected images, record the reference-to-design mapping, and carry it into every downstream prompt. Prefer those concrete references over generic prestige anchors or bank defaults. Current task instructions, scientific correctness, output requirements, and an established document palette or figure-series identity still govern. Check the prompt for explicit imitation instructions and exclusions; when an image is generated, compare its actual appearance against the references and revise unmet requirements. For another user, seek that user's preference evidence.

## Workflow

### 1. Read Only The Figure Context You Need

Read the smallest set of files needed to understand the figure's job:

- the target source file for the section, slide, or page the figure supports
- neighboring text only when needed to understand scope or terminology
- existing figures only if the user wants a refresh rather than a fresh figure
- one to three references from `references/reference-bank.md` when the user
  wants grounding in an existing visual language
- use `../../figure-references/index.md` only as an extra local archive when it
  actually exists in the current repo

Do not read the whole repo just to draft one figure.

For paper and proposal explanatory figures, especially overviews and Figure 1, resolve `editable-figure` through the normal skill lookup. Read its `references/gallery/index.md` and the relevant feedback and images. Follow its durable update procedure for new preferences, including project feedback outside bootstrap-managed copies. Record the reference-to-design mapping in the figure brief: selected IDs, confirmed qualities to imitate, their concrete treatment, and boundaries. Carry it into every downstream prompt with reference images when supported. These design references do not change the requested output format or require a PowerPoint build. Confirmed preferences override reusable defaults throughout this workflow for the affected dimension. This includes text density, cartoon treatment, and photorealism guidance in `references/prompt-design.md` and `references/external-handoff.md`. Reserve editable label regions when the image model cannot render the required technical text reliably.

### 2. Decide Whether The Figure Is Worth Making

Add or refresh a figure only when it compresses logic better than prose.

Typical cases:

- intro or overview figure for the end-to-end project or system logic
- thrust or aim figure for a pipeline, mechanism, or layered method
- timeline or work plan figure for evaluation and coordination
- ecosystem or adoption figure for capability-building efforts
- evidence or impact figure when adoption or prior-system footprint matters

If the figure would only restate nearby sentences without clarifying structure,
say so and avoid unnecessary figure bloat.

### 3. Pick A Figure Archetype Before Writing The Prompt

Reduce the request to one archetype first:

1. `overview-architecture`
2. `local-mechanism-or-subsystem`
3. `workflow-or-method-pipeline`
4. `method-composite`
5. `concept-illustration`
6. `timeline-or-work-plan`

Then choose the downstream generation path using
`references/tool-selection.md`.

For Yue Zhao's paper and proposal figures, take the primary reference and any complementary donors from the required reference-to-design mapping above. They can set composition as well as style; bank donors fill only choices the mapping leaves open. Otherwise, when helpful, also choose:

- one structural donor from `references/reference-bank.md`
- at most one or two style donors from the same bank or the `editable-figure` gallery; confirmed preferences take priority over bank `liked_traits`

Do not average many references into one prompt.

### 4. Distill A Figure Brief Before Writing The Prompt

Before drafting the final prompt, distill a figure brief with:

- figure goal
- one-sentence reviewer takeaway
- target section and file
- required boxes, actors, or stages
- required arrows or dependencies
- reference-to-design mapping: gallery IDs, confirmed qualities to imitate, their concrete treatment, and qualities to avoid
- suggested layout
- short in-figure text
- caption draft
- recommended downstream generation path
- recommended file or asset destinations

This brief is the local source of truth. The prompt pack is the primary
deliverable for downstream models.

Do not let the figure collapse into a plain box-only wireframe unless the user
explicitly asks for a minimal placeholder. When the figure is proposal-facing,
use a light visual language such as icon badges, grouped regions, or
restrained illustrative cues when those cues improve readability.

### 5. Choose The Downstream Generation Path Before Writing The Prompt

For Yue Zhao's new paper/proposal overviews, new standalone mechanism figures, and substantial redesigns, apply the concept-first default in `editable-figure`: plan an actual whole-figure image-generation draft before editable reconstruction. An object asset sheet or a code-rendered box layout does not complete that stage. Keep a prompt-only request prompt-only, while making this intended downstream sequence explicit. Use `editable-figure`'s scoped exceptions for accepted-layout edits, small insets within accepted figures, exact supplied-layout reproduction, and explicitly requested native-only drafts; do not launch extra generators without authorization.

Do not over-prioritize format purity. First choose the prompt and tool path
most likely to yield a strong final figure within the user's time, tooling,
and revision constraints.

Common paths:

1. direct LLM generation as the final deliverable
2. LLM-generated first draft plus local cleanup
3. fully local diagramming or code-generated figure
4. hybrid pipeline with multiple tools

Direct model output is acceptable when:

- the user mainly wants a visually strong figure fast
- future edits are likely to be minor
- the model can already deliver good typography and composition for the task
- exact local editability is less important than final appearance

Prefer editable local sources when:

- many collaborators will revise the figure repeatedly
- labels or layout will change often with the text
- the figure encodes precise graph, chart, or workflow logic that benefits from
  deterministic updates

Once the path is clear, produce one copy-ready prompt pack for that path.

### 6. Format One Prompt The Model Can Actually Use

When the downstream path uses an outside image model, do not dump the entire
figure brief into the model. Produce:

1. a short local source-of-truth note for the repo
2. one model-neutral prompt meant to be copied into the outside tool

That prompt should be self-contained and visually directive, but not overloaded
with internal reasoning, review rubrics, or repo-specific workflow notes.

Use the cross-model guidance in `references/prompt-design.md`. The prompt
should usually contain these layers in this order:

- figure type and core message
- reviewer takeaway
- required layout and semantic elements
- required arrows or dependencies
- style references: gallery images when supported, plus transferable qualities in words
- visual-quality layer
- output-quality layer

Prefer prompts that tell the rendering model:

- what kind of scientific figure this is
- what the central semantic blocks are
- how directionality should read
- how color should map to functional role
- what aesthetics to avoid

Do not ask the rendering model to optimize for the repo's internal workflow.
That part belongs in the local brief, not in the copied prompt.

Never ask an outside image model to produce code-based formats such as TikZ,
SVG, Graphviz, or Mermaid. These formats severely limit visual quality. When a
code-based source is needed, the agent should write it directly.

### 7. Support Third-Party Tools Without Depending On Them

When the user wants to use Gemini, Sora, Midjourney, Flux, or similar tools:

1. convert the figure brief into a clean prompt pack
2. tell the user whether the expected output is:
   - a reference draft
   - a near-final candidate
   - an acceptable final deliverable
3. if the returned asset should stay in the repo, place it under
   `<work-dir>/figure-src/reference/` or another agreed local folder
4. treat those assets as inspiration, a draft, or a final candidate depending
   on the task
5. if the first output is close but not right, reprompt with delta feedback
   before escalating to cleanup or rebuild
6. rebuild or clean up locally only when the figure quality or editability
   still falls short

When reprompting a close-but-not-right draft:

- explicitly keep the parts that already work
- describe only the deltas that must change
- change one to three dimensions at a time unless the concept is fundamentally
  wrong
- restart from the original brief when repeated delta prompts are drifting or
  contradicting each other

Useful delta instructions include:

- keep the current layered layout but enlarge all labels by 20%
- preserve the left-to-right flow and simplify the icon set
- keep the composition and color roles, but make the causal arrows explicit
- keep the overall structure and replace decorative art with cleaner schematics

Do not force a rebuild just because the output is raster or not locally
editable. Rebuild only when the figure still fails the user's actual quality or
maintenance needs.

### 8. Treat Editability As A Decision Variable, Not A Hard Rule

Editable local sources are sometimes helpful, but they are secondary here.
Recommend them only when they materially improve iteration or reuse.
Otherwise, optimize for a strong prompt and final figure quality.

Possible outputs include:

- direct image-model output
- Figma or PowerPoint source
- draw.io or SVG
- Graphviz or Mermaid source
- matplotlib or another plotting script
- TikZ when LaTeX-native generation helps
- hybrid source plus exported PDF or PNG

For complex figures, it is still acceptable to produce:

- a strong figure brief
- a prompt pack for outside generation
- a local cleanup plan
- a skeletal editable source when fully polished auto-generation is unrealistic

When drafting local skeletons or cleanup plans:

- avoid crude box farms unless structure is the only goal
- route arrows deliberately; avoid diagonals that create visual confusion
- prefer grouped regions, icon badges, and 1-2 accent shapes over decorative
  clutter
- keep in-figure text short enough that later style polishing remains easy

### 9. Write Outputs Into Stable Locations When The Workspace Has Them

Use these repo locations:

- `<work-dir>/figure-spec/` for figure briefs and prompt packs
- `<work-dir>/figure-src/` for editable local sources or intermediate assets
- `<work-dir>/figure/` for final exported assets
- `<work-dir>/figure-src/reference/` for external reference images or drafts

When the workspace does not already use these folders, create only the folders
that materially help organization. Do not force repo-specific directories onto
a task that only needs one prompt file or one final image.

When the user explicitly wants an outside-model prompt, save a dedicated prompt
file under `<work-dir>/figure-spec/` with a stable name such as
`<figure-name>-universal-prompt.md`. Keep the file easy to copy:

- short title
- optional one-line note
- one fenced `text` block containing the actual prompt

## Output Style

When using this skill, prefer one of these outcomes:

- a figure recommendation with rationale and no new file
- a figure brief and caption draft
- a figure brief plus a prompt pack for outside tools
- a prompt-only file meant to be pasted into an external image model
- a prompt pack plus generation-path recommendation and filenames
- a prompt pack plus follow-up guidance for improving an outside draft

Keep the output practical. The main value is reducing manual figure-design work
while making it easier to get to a strong downstream prompt and a strong final
figure.