Visualization-driven development
Treat the visualization as the feature's hypothesis-and-check, not an
afterthought.
The loop
- Build the visualization first, before implementing the feature.
Generate it against expected, synthetic, or baseline data so it cements
understanding and states an explicit hypothesis: what should the result
look like if the feature works?
- Then implement the feature.
- Then regenerate the same visualization for real, against actual output,
and compare it to the hypothesis to confirm or refute it.
Prefer watchable or lookable artifacts — overlays, rendered media, charts,
side-by-side before/after — over terminal tables when the effect is spatial or
temporal. Tell the user where the artifact is saved so they can look at it.
Prefer videos to convey understanding
Generate videos (before, after, or both side-by-side) whenever they would help
the user understand the effect — and that is most of the time, not the
exception. A playhead sweeping an analysis, an overlay riding the actual
footage, an animated before/after: these convey temporal and spatial behavior
that a still frame cannot, and they are how the user catches errors a static
artifact would hide.
- Default to producing a video when the effect is temporal, spatial, or
sequential (signals over time, tracking or overlays on media, transitions,
simulations, state evolution). Skip it only when a video genuinely adds
nothing over a still — and say so explicitly when you skip.
- A "before" video shows the old, baseline, or naive behavior; an "after"
shows the new, correct behavior; both, side-by-side or sequential, is ideal
for proving a change did what was intended.
- Make videos honest: label what each panel is, and if an artifact is later
found wrong or misleading, keep it but caption it as not-entirely-correct
rather than silently deleting it.
- Always tell the user the path, and surface the file so they can watch it.
1---2name: viz-driven-dev3description: Hypothesis-first visualization workflow for feature development - build the plot, overlay, rendered artifact, or video that would show the feature's effect before implementing it, then regenerate the same artifact from real output to confirm or refute the hypothesis. Use when building or changing a feature whose effect can be seen or watched - signals over time, overlays on media, spatial or sequential behavior, state evolution, or any before/after comparison.4---56# Visualization-driven development78Treat the visualization as the feature's hypothesis-and-check, not an9afterthought.1011## The loop12131. **Build the visualization first, before implementing the feature.**14 Generate it against expected, synthetic, or baseline data so it cements15 understanding and states an explicit *hypothesis*: what should the result16 look like if the feature works?172. **Then implement** the feature.183. **Then regenerate the same visualization for real**, against actual output,19 and compare it to the hypothesis to confirm or refute it.2021Prefer watchable or lookable artifacts — overlays, rendered media, charts,22side-by-side before/after — over terminal tables when the effect is spatial or23temporal. Tell the user where the artifact is saved so they can look at it.2425## Prefer videos to convey understanding2627Generate videos (before, after, or both side-by-side) whenever they would help28the user *understand* the effect — and that is most of the time, not the29exception. A playhead sweeping an analysis, an overlay riding the actual30footage, an animated before/after: these convey temporal and spatial behavior31that a still frame cannot, and they are how the user catches errors a static32artifact would hide.3334- Default to producing a video when the effect is temporal, spatial, or35 sequential (signals over time, tracking or overlays on media, transitions,36 simulations, state evolution). Skip it only when a video genuinely adds37 nothing over a still — and say so explicitly when you skip.38- A "before" video shows the old, baseline, or naive behavior; an "after"39 shows the new, correct behavior; both, side-by-side or sequential, is ideal40 for proving a change did what was intended.41- Make videos honest: label what each panel is, and if an artifact is later42 found wrong or misleading, keep it but caption it as not-entirely-correct43 rather than silently deleting it.44- Always tell the user the path, and surface the file so they can watch it.
dm1681