/figure-composer

name: figure-composer
description: 'Compose one publication-grade multi-panel figure. Start from a one-line claim plus immutable data Artifact Version references, or inspect an existing figure and draft its outline directly. Plan a 12-column panel outline, delegate one worker per panel, compose and inspect the result, then run at most three adversarial review rounds while regenerating only affected panels. For a standalone plot use `figure-style`; for whole-paper figure ordering use `paper-narrative`.'
license: Apache-2.0

Figure Composer — narrative → panels → compose → adversarial loop

`figure-composer` is the outer workflow for one multi-panel figure. Use the `figure-style` rules while planning and reviewing; every panel worker uses those rules independently. Run `paper-narrative` first when the paper-level figure sequence is still undecided.

Open-Science Notebook call

Every `notebook_execute` request whose `code` uses a function named in this skill includes this skill ID:

{ "kernelSkillIds": ["figure-composer"], "code": "print(figure_outline_schema())" }

`kernelSkillIds` contains the skill ID; function calls belong in `code`. Call the named functions directly without an import or discovery step.

Inputs

• `claim`: the one sentence the figure makes true without surrounding prose.
• `dataVersionIds`: immutable Upload or Artifact Version identities grounding

the panels.

• `width_mm`: venue column width, commonly 85–89 mm single or 174–183 mm double.
• `rulesVersionId`: immutable Artifact Version containing the design rules used

by the composite reviewer.

• `delegatePrefix`: short branch-unique prefix for panel and reviewer child names.

Run this workflow only in the Main/root agent. Delegated children cannot call `host.delegate`, so the whole composer cannot itself be delegated.

Entry points

• **From a claim:** Main writes the outline in step 1 from the claim, data, and

`figure-style` rules.

• **From an existing figure:** inspect it with `host.viewImage`, then have Main

draft and review the outline directly. Current `host.llm` calls do not accept images, so do not add a second hidden inference step. Pixels cannot supply Artifact Version identities; fill `data_vid` from the provided data.

1. Narrative → panel outline

Main produces a `panel_outline` matching `figure_outline_schema()`:

{
  "claim": "…",
  "width_mm": 180,
  "ncol": 12,
  "row_heights_mm": [40, 60, 46, 52],
  "panels": [
    {
      "letter": "a",
      "role": "schematic",
      "row": 0,
      "col": 0,
      "colspan": 12,
      "chart_family": "schematic overview",
      "message": "…",
      "data_vid": null,
      "ask": "…"
    },
    {
      "letter": "b",
      "role": "primary",
      "row": 1,
      "col": 0,
      "colspan": 7,
      "chart_family": "scatter + trend",
      "message": "…",
      "data_vid": "…",
      "ask": "…"
    }
  ]
}

Outline rules:

• A is the context-free hook: schematic or hero, normally full width.
• B carries the claim: it should make the sentence true on its own.
• Remaining panels add evidence in descending importance.
• Use one row per sub-claim, normally 5–10 panels, and a 12-column grid.
• Every non-schematic `data_vid` must be one of the supplied immutable Version

identities. Do not invent or rewrite Version IDs.

• Set `fixed_panel_set: true` only when the user explicitly requires the exact

listed panels.

Geometry helpers reject duplicate panel letters (case-insensitive), overlapping grid spans, panels outside the grid, and invalid or subpixel grid dimensions. Use unique panel identifiers and non-overlapping positive spans within the grid.

Review the outline before fan-out. Use the schema as a contract; Main does the reasoning and does not call `host.llm` to generate the outline again.

2. Fan out panel workers

Generate each task in Python with `panel_task(outline, letter, fig_label)`. The returned task contains the complete panel procedure. Pass it unchanged on the first render and supply the panel's data Version in `inputs`.

Dispatch from `repl_execute`. `host.delegate` accepts at most four children per atomic call, so send ordered waves of no more than four. Each request uses this output schema:

const panelOutputSchema = {
  type: 'object',
  additionalProperties: false,
  required: ['panelVersionId', 'labelsUsed'],
  properties: {
    panelVersionId: { type: 'string', minLength: 1 },
    labelsUsed: { type: 'array', items: { type: 'string' } }
  }
}

Use `wait: false`, then collect the exact `{ frameId, attemptId }` receipt handles. A collect timeout ends observation, not the child Attempt: collect the same handles again while any remain running. Retry only after a terminal failure or an explicitly rejected output, using a fresh child name. Panel workers must submit their structured result with `host.submitOutput` before finishing. Reject a non-completed/error child, missing or unsatisfied structured output, a missing or duplicate expected `panel_<letter>.png`, or a mismatch between its Artifact `versionId` and `structuredOutput.panelVersionId`. MIME metadata may be absent; the exact filename and Version identity are the binding checks. Return each wave's validated `{ letter, versionId }` values from the `repl_execute` call instead of relying on local `const` or `let` declarations to survive a later call.

Keep finalized Version identities in outline order. Temporary paths are never the Agent-to-Agent contract. Child names remain occupied after settlement, so use a unique `delegatePrefix` and round number.

3. Compose and bind the producer Run

Generate a producer task with `composition_task(outline, panelVersions, fig_label)`. Main's newly written Artifact can remain pending until its turn ends; the producer child publishes a finalized composite that the reviewer can use. Pass the ordered panel Version identities in `inputs` and require this output schema:

{