# Milestone 3 product brief

Date: 2026-07-19
Status: implemented locally; public deployment deferred
Authority: user-supplied judge experience preferences interpreted through
`product_doctrine.md`

## Product story

Milestone 3 should make a first-time judge feel the power of visualization:

> A single chart can carry far more information, attention, and persuasive force
> when its visual hierarchy is designed deliberately rather than naively.

Chartsmith should make that difference immediately visible. The primary proof is
the source-to-redesign transformation: the same underlying evidence becomes
faster to perceive, easier to remember, and more effective at communicating its
point.

The interface should also make clear why Chartsmith is a product rather than a
thin prompt around a general chat or image-generation model. It should expose
the useful consequences of the system's structure without asking the judge to
read implementation details.

## Judge takeaway

Within roughly twenty seconds, a judge should understand:

1. Chartsmith accepts a chart image alone.
2. It reasons about what the chart communicates, not only how it looks.
3. It explores and selects a materially stronger visual idea.
4. It renders, inspects, and repairs the actual output.
5. The result communicates more effectively than the source while preserving a
   minimum epistemic floor.

The intended remembered impression is:

> AI can reason about visual communication and use that reasoning to transform
> how powerfully a chart delivers information.

## Product value beyond a single model call

The product must not depend on complexity as an abstract selling point.
Complexity is valuable only where the judge can observe a better consequence.

Chartsmith's differentiating mechanisms are:

- structured perceptual reconstruction before design;
- explicit identification of the strongest defensible message;
- multiple materially different concepts with autonomous selection;
- access to non-library-native visual treatments;
- deterministic ownership of exact text and data-bearing geometry when needed;
- full-size and embedded-size inspection of the rendered result;
- targeted repair of concrete visual and epistemic problems;
- bounded execution, resumability, provenance, and inspectable evidence.

Milestone 3 should demonstrate these mechanisms in three ways:

1. **Transformation evidence**
   - Put the source and final chart in direct visual relationship.
   - Explain what information became easier or faster to perceive.

2. **Process evidence**
   - Reveal meaningful intermediate results as they become available.
   - Show when inspection finds a problem and when a repair changes the result.

3. **Controlled differentiation evidence**
   - For at least one submission example, retain a direct single-call baseline
     produced from the same image with a simple "improve this chart" objective.
   - Compare it with the full Chartsmith result using the same release concerns.
   - Present the comparison honestly; do not manufacture an artificially weak
     baseline or claim that every direct model call must fail.

The claim to prove is not that a general model can never redesign a chart. It is
that Chartsmith makes strong results more deliberate, inspectable, repairable,
and reliable while supporting a more ambitious visual transformation.

## Experience principles

### Final transformation first

The redesigned chart remains the hero. The interface should not resemble a
workflow monitor, developer console, or audit report.

### Visible, meaningful progress

A full run may take tens of minutes. During that time the judge should receive
finished, user-facing pieces of work rather than a spinner or labels such as
"running stage 3."

Each completed stage should answer a human question:

| Workflow stage | User-facing question | Presentation |
| --- | --- | --- |
| Input | What did I give Chartsmith? | Source preview and basic image facts |
| Reconstruction | What does Chartsmith think this chart says? | Message, visible structure, strengths, limitations, and meaningful uncertainty |
| Design exploration | What stronger ideas did it consider? | Three concise visual-direction cards; the autonomous selection is highlighted |
| Rendering | What did the chosen idea become? | The latest candidate image and a short description of its visual mechanism |
| Review | What did Chartsmith inspect? | Concrete findings at full and embedded sizes, translated into plain language |
| Repair | What changed because of the inspection? | Named defect or integrity issue, the correction, and the updated candidate |
| Final evaluation | Why is this ready? | Source/final comparison, communication gain, integrity result, and concise confidence statement |

Intermediate results must never be raw JSON, schema fields, prompts, token
metrics, or machine logs. They should be projections of canonical run artifacts
into deliberately written UI content. Detailed artifacts and provenance may be
available behind an expandable evidence view.

### Progress must be truthful

The product may report only work that has actually completed. It must not use
fake percentages or imply that a stage passed before its contracted artifact was
validated. If exact completion time is unknown, show completed stages, the
current activity, and what will happen next rather than an invented countdown.

### Confident but epistemically honest

Chartsmith should speak as an opinionated visual editor:

- lead with the communication idea it selected;
- explain important changes directly;
- state uncertainty only where it affects interpretation;
- avoid apologetic or generic caveats;
- never present an inferred value or causal claim as verified fact.

### Examples are a complete product path

Curated examples are not fallback screenshots. Each should provide the same
high-quality journey as a live run:

- source chart;
- polished stage presentations;
- intermediate candidates and repairs where available;
- final chart;
- concise design explanation;
- production- and epistemic-integrity results;
- inspectable provenance.

Examples should load immediately so the core product can be understood even
when a live run has not finished.

## Primary flows

### Explore an example

The judge opens Chartsmith, sees a strong source/final transformation, and can
step through how the system understood, designed, inspected, and repaired it.
No account, setup, or waiting is required.

### Run Chartsmith

The judge uploads a chart image, starts one autonomous run, and follows completed
stage presentations while the workflow continues. The run does not ask for
design choices. The user can leave and return without losing completed work.

### Inspect the result

The final view leads with the redesigned chart and source/final comparison. It
then gives a compact explanation of the design decision and communication gain.
Detailed reconstruction, review history, and provenance are available but do
not dominate the page.

## Explicit non-goals

Milestone 3 is not:

- a collaborative chart editor;
- a prompt-writing interface;
- a dashboard of JSON artifacts or model traces;
- an alternative-selection workflow for the user;
- a promise of exact data extraction;
- a redesign of the promoted Milestone 2 engine;
- a broad benchmark claiming that Chartsmith always defeats general chat.

## Deferred authority decisions

Public deployment details will be discussed later. Implementation planning may
continue, but Codex must not publish, incur material cost, expose credentials, or
change repository visibility without the relevant user authority.

Deferred items include:

- hosting and model-service accounts;
- spending limits;
- public or private repository status;
- domain and deployment ownership;
- license and attribution confirmation for submission examples;
- publication of the demo, repository, and submission materials.
