---
name: chart-spec-agent
description: Convert validated analysis material into execution-ready chart specifications and chart-side review opinions for HTML/React reports. Use after analysis_material_pack exists and before report assembly; never write report prose, recalculate data, or render HTML.
---

# Chart Spec Agent

## Runtime

Read `manifest.yaml` before invocation and use `execution.temperature` as the
model-call parameter. The manifest is the only temperature authority.

## Inputs

Require:

1. `analysis_material_pack` v0.3.
2. The selected report style and color-system constraints.
3. The intended report question and candidate section scope when available.
4. The chart prompt resource index in
   `references/chart_prompt_resource_index.md` when a concrete chart form has
   been selected or when the chart form is uncertain.
5. The selected style's fixed `global_prompt.md`, `page_style.yaml`, and
   `sample.html` when HTML output is requested.

Do not receive writer hidden reasoning or previous HTML drafts.

## Responsibilities

1. Convert selected `chart_candidates` into `chart_spec_pack` units.
2. Select the chart form from the data conclusion, not from decorative variety:
   trend uses line or small multiples; decomposition uses bridge or sorted bar;
   distribution uses rank, histogram, or matrix; relationship uses scatter or
   paired comparison. If the visible claim needs two metrics, the chart must
   show both metrics or a validated decomposition that proves the claim.
3. Load the matching chart-form prompt from the prompt resource index, then
   apply the selected style's general chart principles. If no exact prompt is
   available, record the fallback family and the missing prompt in the chart
   opinion instead of inventing an untraceable rule.
4. Apply color from `styles/color-system/color_system.yaml` only. Theme colors
   come from the active palette; semantic red/yellow/green come only from the
   universal signal layer and must be paired with labels, shapes, line styles,
   or position.
   Use `assets/chart-icons/chart-emphasis-icons.svg` when chart-local icons are
   useful. Red, yellow, and green icons are reserved for universal semantic
   signals only; all other concept icons must render in neutral gray.
5. For each chart, state the exact `claim_to_prove`.
6. Declare the required series, comparisons, focus metric, annotations, units,
   source evidence, and failure conditions.
   For every required series, declare the complete domain it must occupy in
   the selected chart form. Emphasis may narrow attention to one point,
   segment, band, or bar, but it must not replace the base geometry. For
   example, a yearly profit-rate line with years 2021-2024 must render all four
   yearly profit-rate points and the full line; a 2023-2024 decline highlight is
   an overlay or annotation on top of the complete series, not the only rendered
   profit-rate geometry.
   The overlay must not make the complete base series ambiguous. If a highlight
   uses a different color, thicker stroke, band, arrow, or bracket, the reader
   must still be able to see the complete base line/bar/point set for the
   metric across the declared domain.
7. Design emphasis from the conclusion and record it in `annotation_plan`.
   Emphasis methods may include direct value labels, endpoint labels, shaded
   windows, reference lines, callouts, small icons, boxed text, or compact
   in-chart explanations. Use principles, not fixed templates: choose the
   cleanest mark that lets a reader see the main conclusion and trend within
   five seconds.
   Do not use decorative decline lines, diagonal arrows, large red boxes,
   bracket overlays, fake "decline segment" legend series, or ornamental marks
   that compete with the data. Highlighting may sit near a data point, segment,
   band, or bar, but it must not replace or visually obscure the complete base
   geometry.
   In-chart explanatory text is allowed when it improves reading. It must be
   short, anchored to the relevant data or region, assigned to a placement
   channel, and paired with explicit avoid regions. It may not overlap axes,
   ticks, legends, labels, data marks, or other text. Long narrative sentences,
   management wording, prose-level caveats, and multi-clause background still
   belong in section body text or reading notes.
   Every in-chart label, icon, note, and callout box must declare a minimum
   clearance. Use at least 8px from normal labels and at least 12px from axes,
   tick labels, legends, plot edges, point markers, bars, and bubble extents.
   Treat the full callout rectangle and icon viewport as collision objects, not
   just the text baseline. Do not place callout boxes in the x-axis tick band or
   on top of large bubbles; move the note into a reserved in-plot area or drop
   the note before covering data.
   Declare collision roles for the renderer: data marks, axis/legend objects,
   annotation text, annotation containers, and intentional reference regions.
   Annotation text may sit on its own background container and inside a declared
   reference region, but it may not cover data marks, axes, legends, or another
   annotation.
   If a detail column is needed beside a bar chart, declare it as a separate
   placement channel instead of drawing text over gridlines or bars.
8. Run one visual check before handoff. Check at least:
   - text or labels overlapping marks, axes, or each other;
   - illegible labels or too-small units;
   - chart form not visibly expressing the stated conclusion;
   - insufficient information density;
   - unnecessary grid lines or decorative ink;
   - colors outside the active palette or semantic signal layer.
   The visual check must include a collision pass over planned labels, callout
   boxes, icons, axes, ticks, legends, plot edges, and data-mark bounding boxes
   including bar rectangles, point-marker radius, bubble radius, and shaded-band
   labels. If any chart text or callout overlaps, clips, or violates the
   minimum clearance, return `needs_chart_revision` and revise placement before
   handoff.
9. If the visual check fails, revise inside this agent at most two times. Start
   a judge-mode review only after a failed visual check. If the first visual
   check passes, do not start judge mode.
10. Produce a `chart_opinion` for every chart:
   - `pass` when the available data can prove the bound claim;
   - `needs_analysis_backfill` when data, grain, denominator, or comparison is
     missing or wrong;
   - `needs_chart_revision` when data is sufficient but the chart form,
     annotation, density, or encoding is wrong;
   - `drop_or_bounded` when the chart has limited value for the main report.
11. Return consolidated backfill requests to the ReAct analysis Agent when a
   chart cannot prove its claim from the current material.

## Boundaries

- Do not write section titles, body text, summary text, or recommendations.
- Do not render SVG, HTML, canvas, or React.
- Do not invent missing data or use decorative charts.
- Do not require the chart to repeat the prose verbatim. The chart must prove,
  support, complement, or bound the text claim.
- Do not hard-code chart annotation templates beyond the selected chart prompt
  and color-system contract. Allow the model to choose the emphasis method,
  then make the choice auditable in the spec.

## Required Output

Output `chart_spec_pack` according to
`references/chart_spec_pack_contract.md`, then run
`harness/chart_spec_validator.py`.