# Chartsmith product doctrine

Date: 2026-07-19
Status: canonical product direction for Build Week and later design decisions

This document records the product preferences supplied by the user. It is the
authority for what Chartsmith should optimize for. Implementation plans may
change; this doctrine should change only when the user's product intent changes.

## Product thesis

Chartsmith explores how far current multimodal AI can go in making a chart more
powerful from the chart image alone.

Good visualization is not treated as a mysterious expert-only craft. A capable
model can inspect what a chart communicates, reason about what helps or obstructs
that communication, and make purposeful design decisions. Modern image
generation also permits visual forms and details that conventional chart
libraries make difficult or impossible. Chartsmith should actively use that
freedom rather than behave like an automatic restyling preset.

The intended result is a chart that catches attention and communicates its point
to a busy audience more quickly, clearly, and persuasively than the input.

## Intended product experience

- **Image in:** a chart image is sufficient input. Raw data, source context, and
  design instructions must not be required.
- **One-shot:** the user starts one autonomous run. Chartsmith does not ask the
  user to interpret the chart, select a design direction, or provide design
  expertise.
- **One authored result:** internal exploration and repair are allowed, but the
  product returns one confident final redesign rather than making the user manage
  alternatives.
- **AI-owned design judgment:** Chartsmith may infer the strongest useful message,
  change chart type or composition, introduce visual devices, and depart
  materially from the source when doing so improves communication.

Optional context or raw data may become a future enhancement, but the image-only
path is the defining product challenge and must remain fully supported.

## Optimization priorities

Once the hard release gates below are satisfied, prefer designs in this order:

1. **Communication power** — the important point is faster to perceive, easier to
   understand, and more persuasive for the intended audience.
2. **Design intelligence and authorship** — the output contains purposeful visual
   ideas, not just cleaner defaults or cosmetic restyling.
3. **Interestingness in service of the message** — the redesign gives the user a
   useful idea they were unlikely to have requested themselves. Novelty is not
   the primary goal, but a boring near-copy is a product failure.
4. **Perceptual fidelity** — reconstructed values and relationships remain close
   enough that ordinary viewers are not misled by visible differences.
5. **Auditability** — the run retains enough evidence to explain what was
   reconstructed, inferred, changed, and checked, without turning the main
   product experience into an audit report.

This ordering intentionally gives Chartsmith more authority than a conservative
professional chart-correction tool.

## Hard release gates

### Production integrity

The final chart must be free of visible production defects. Reject or repair any
output with:

- overflow, cropping, or broken line wrapping;
- overlapping text, marks, legends, or annotations;
- strange annotation placement or backgrounds that obscure the data;
- visibly bad margins, spacing, alignment, or optical centering;
- tiny, unreadable, malformed, or inconsistent typography;
- distorted geometry or other image-generation artifacts;
- defects that become apparent at the product's normal embedded display size.

A strong concept does not compensate for a visible defect. Humans attend to these
failures immediately, so production integrity is binary at release even though
most design qualities remain continuous.

### Minimum epistemic integrity

Image-only reconstruction is approximate, and small imperceptible numerical drift
is acceptable for this product. It must still not produce a visibly false chart.
The redesign must not:

- reverse an obvious ranking, trend, sign, or major proportion;
- invent or remove a major category or series without a defensible visual basis;
- change visible units or the qualitative meaning of an axis;
- assert a specific causal or factual claim unsupported by the source image;
- conceal material uncertainty that is plainly encoded in the source.

When exact values cannot be recovered, Chartsmith should avoid false precision
and design around the reliably visible relationships. This floor protects the
product thesis without turning Chartsmith into a high-stakes verification system.

## Creative authority

Chartsmith should be willing to overstep the source's design choices. It may:

- identify a stronger defensible message than the source foregrounds;
- reorganize hierarchy and composition around that message;
- change visual grammar when another form communicates better;
- use illustration, spatial metaphor, emphasis devices, or bespoke visual details
  that standard chart libraries do not readily support;
- make an opinionated selection rather than deferring to the user.

Creative elements must remain purposeful. Decoration that competes with the
message, ambiguous data-like ornament, or novelty without communication gain is
not a success.

## What counts as failure

The run fails the product intent if any of the following is true:

- the output is almost the same as the input, with only generic polish;
- the redesign is technically neat but no faster or more persuasive to read;
- an interesting idea weakens the chart's actual message;
- visible production defects remain;
- approximate reconstruction becomes an obvious semantic or data error;
- the workflow requires the user to supply design judgment;
- internal caution makes Chartsmith routinely retreat to safe, default charts.

## Product boundaries

Chartsmith is not currently:

- a professional tool for audited, regulated, scientific, financial, or other
  high-stakes reporting;
- a guarantee of pixel-perfect data recovery from an image;
- a general chart digitization or raw-data extraction service;
- a conventional chart-library template recommender;
- a collaborative design editor that expects iterative user direction.

These are deliberate boundaries, not missing disclaimers to dominate the user
experience.

## Learning philosophy

Workflow improvement should resemble careful human learning:

1. use a very small number of concrete charts;
2. inspect each input and output in depth;
3. identify the most important failure, not every measurable difference;
4. diagnose why the workflow produced it;
5. make one coherent improvement;
6. test that improvement on the original case and a contrasting case;
7. retain it only when the reasoning and visual evidence support it.

Large-batch prompt search, gradient-like optimization, and score chasing are not
the default development method. Quantitative axes may organize evidence, but
visual judgment and mechanism-level diagnosis lead.

## Judge-facing product presentation

The judge-facing product should make people feel the power of visualization:
how much more information, attention, and persuasive force one chart can deliver
when it is designed efficiently rather than naively.

The product must also demonstrate why Chartsmith adds value beyond handing the
same image to a general chat model. It should not argue that workflow complexity
is valuable by itself. It should show the consequences of its mechanisms:
structured understanding, materially different concepts, autonomous selection,
rendered-image inspection, targeted correction, and a final result that is both
more ambitious and more dependable.

Long execution should become a meaningful product experience. As contracted
stages complete, the interface should reveal polished intermediate results that
are useful to read while waiting:

- what Chartsmith believes the source communicates;
- what stronger visual directions it considered;
- which direction it selected and why;
- what the first rendered result looks like;
- what visual or epistemic problems review discovered;
- how repair changed the result;
- why the final chart is ready.

These results must be translated into user-facing language and visual
presentation rather than exposing JSON, schemas, prompts, or technical logs.
Progress must remain truthful and tied to completed artifacts.

Curated examples should include the same intermediate journey and load
immediately. The final chart remains the hero, with a concise, confident, and
epistemically honest explanation. Detailed provenance and audit evidence remain
available without dominating the primary experience.

## Derived implementation implications

The following are Codex's current interpretation of the doctrine, not additional
user preferences:

- preserve the deterministic outer orchestrator so one-shot autonomy is
  reproducible and bounded;
- give the creative stages broad authority inside explicit artifact contracts;
- explore multiple materially different concepts internally before committing;
- combine generative visual flexibility with deterministic text or geometry
  control when that is the best way to eliminate production defects;
- make rendered-image inspection and targeted repair mandatory;
- compare the final output directly with the source on communication,
  persuasion, memorability, authorship, and visible integrity;
- preserve the current v2.6 workflow as a baseline while developing the new
  direction in an isolated vNext track.

These implications may be revised when implementation evidence suggests a better
mechanism, provided the product doctrine remains satisfied.

## Preference status

The user has supplied enough product-level preference to begin Milestone 2. No
additional abstract philosophy question is currently blocking technical planning
or implementation.
