A guidance document for building visualizers that vary

HOWTO-visualizers.md gets a scene working. Nothing said how to make one look
different from song to song, which is the thing the library is worst at and the
thing every measurement this epic has been about.

Written as evidence rather than advice: each claim carries the number behind it,
so a later change can contradict it. Several already contradict things believed
earlier in the same week.

It records the failures at least as carefully as the wins, because they were more
informative and each looked obviously right beforehand — effects as parameters
inflating a score without changing a picture, concentrating disturbance instead
of adding it, the roster-size theory that a direct sweep found to be nothing, and
reading a form as a metric rather than drawing it. It also documents what the
descriptor cannot see, since half of "why is my score low" is there: brightness,
colour, rotation, quality, and layout for anything that fills the frame.

And it is explicit about which numbers to trust. Direct render comparisons have a
noise floor of zero; aggregate ratios swing enough to have produced four
withdrawn conclusions in one epic.

Ongoing by design, with the open questions listed: coupling has never moved off
zero, fixed-geometry scenes have no known route to variety, and the 0.04 bar was
set against scores that were depressed by a measurement bug.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

flow-state/debug.html

@@ -50,7 +50,8 @@
             <p>Every visualizer, six times, on six different songs' content — cast,
                ink, lattice, palette and parameters all varying. Sorted least-varied
                first, so the scenes that always look the same come to the top.</p>
-            <div class="meta">~3 min · the one to open when a scene feels familiar</div>
+            <div class="meta">~3 min · the one to open when a scene feels familiar ·
+                <code>HOWTO-variety.md</code> for how to fix what it finds</div>
         </div>
         <div class="card fast">
             <h3><a href="/">the app</a></h3>