# Source Fidelity Review

Task: DIAGRAM-SOURCE-FIDELITY-REVIEW
Date: 2026-05-16

## Clarification

The first diagram experiment batch produced type examples and findings. Those
outputs were reviewed for nonblank rendering, text fit, and broad structure.
They were not accepted as pixel-perfect recreations.

For future work, any task labeled as `recreation` must be evaluated pixel-perfect
against the source reference. Similar structure is not sufficient.

## Required Recreation Workflow

1. Classify the task:
   - `semantic`: explain the concept.
   - `inspired-by-reference`: reuse visual ideas without fidelity acceptance.
   - `recreation`: reproduce the source.
2. For `recreation`, extract the source region first. Ignore browser chrome,
   page headers, footers, and download-site UI unless they are explicitly part
   of the requested diagram.
3. Build a source inventory:
   - page/canvas size and aspect ratio.
   - every container and nested container.
   - all text, including line breaks, rotation, alignment, size, and approximate color.
   - every connector, endpoint, arrowhead, bend point, line style, and label.
   - icons, badges, legend entries, borders, fills, shadows, and z-order.
4. Render the output.
5. Compare source versus output by element or visual region.
6. Correct and re-render until gaps are closed or explicitly documented.
7. If the target cannot support required fidelity, reclassify the deliverable as
   approximation and escalate to draw.io/Lucid for the authoritative artifact.

## Required Source-Free Workflow

Diagrams without a source reference are not exempt from visual precision. They
must be pixel-perfect against their own declared contract before handoff.

1. Define the contract before drawing: canvas size, diagram type, groups, nodes,
   labels, relationships, reading flow, expected connector endpoints, and layout
   constraints.
2. Render the diagram.
3. Inspect the render, not only the source file:
   - text fits inside every container.
   - containers are not too small or visually unbalanced.
   - connector endpoints visibly touch the intended source and target edges.
   - arrowheads are visible and not hidden behind shapes.
   - lines do not cross labels, important symbols, or containers unless explicitly
     justified.
   - labels have clearance from borders, connectors, and arrowheads.
   - whitespace is intentional and does not make the layout feel broken.
4. Correct and re-render before delivery.
5. Record residual issues if a diagram is accepted as an approximation.

## Findings From Current Experiments

### Swimlane

Current output is structurally similar but not pixel-perfect:

- header icons are approximated with text symbols.
- lane header colors and body colors are close but not measured from source.
- node positions and connector bends are simplified.
- source legend and typography are not fully recreated.

Target recommendation for recreation: draw.io or SVG with measured coordinates.
Mermaid recommendation: semantic swimlane only.

### Technology Roadmap

Current output is a representative roadmap, not a source-accurate recreation:

- card sizes, shadows, and exact month grid positions differ.
- icon badges are simplified.
- source legend shape and title band are approximated.
- typography and card spacing were manually adjusted for readability, not exact fidelity.

Target recommendation for recreation: draw.io/SVG with extracted source metrics.
Mermaid recommendation: `gantt` semantic schedule.

### Timeline Infographic

The downloaded PDF contains web page chrome. Current output intentionally uses
only the visible infographic idea and is not a recreation:

- source region extraction was not performed.
- exact colors, icons, and preview card details were not recreated.
- layout was normalized into a clean six-step diagram.

Target recommendation for recreation: first extract the actual infographic image
region, then recreate in draw.io/SVG. Mermaid recommendation: `timeline` semantic
milestones.

### Layered Implementation Architecture

Current output is an abstraction, not a pixel-perfect recreation:

- many source micro-icons and vendor badges were collapsed.
- layer rail labels and system cards were simplified.
- connector count and routing are reduced.
- dense source labels were omitted to preserve readability.

Target recommendation for recreation: draw.io/Lucid with density budget and
source inventory. Mermaid recommendation: semantic layer/component map only.

## Rule Candidates

- `recreation` requires pixel-perfect review.
- `inspired-by-reference` must not be described as recreation.
- PDF/web captures require source-region extraction before diagram authoring.
- Mermaid outputs must be labeled semantic unless exact layout is not acceptance criteria.
- Every recreation needs a source-vs-output gap table before handoff.
- Source-free diagrams need a contract-vs-output gap table before handoff when
  any visual issue remains.