#+TITLE: Proposal: UI features require a prototype phase before build-to-spec
#+AUTHOR: Craig Jennings
#+DATE: 2026-07-11

* The rule (Craig approved promotion 2026-07-11)

When a spec'd feature has a UI, don't build straight from the spec. After the
initial spec, run several UI/UX prototype feedback loops — iteratively driving
the remaining functionality alongside the look and feel — then fold what settled
back into the spec. Only then "build to the prototype": the built feature should
look and behave as close to the prototype as possible, and any deviation is
documented in an addendum section of the prototype/spec itself.

* Where it should live (rulesets session decides exact home)

Two natural homes; probably both:

1. The =brainstorm= skill's Phase 3. Today Phase 3 presents the design in chunks
   and stops. Add: if the feature has a UI, the design isn't "accepted" until it
   has been through a prototype UI/UX phase (several feedback loops), and the
   spec records what the prototype settled. The spec's Next Steps then say
   "build to the prototype," not "build to the spec."

2. A spec-lifecycle rule (=docs-lifecycle.md=, or a small new workflow rule).
   The lifecycle for a UI feature gains a prototype stage between DRAFT/READY and
   build, and the spec carries a "Prototype & deviations" addendum section that
   the build keeps current.

Companion touch points to reconcile: =spec-create= (emit the prototype stage +
the deviations-addendum section for UI specs), =spec-response= (a UI spec
decomposes into a prototype loop first, then build-to-prototype tasks),
=start-work= (its verify phase already drives the UI end-to-end; here the bar is
"matches the prototype," with deviations logged).

* Why — worked example (takuzu, 2026-07-11)

Building the takuzu (Binairo) Emacs game. The spec chose "colored tiles, glyph
overlay optional." Built straight to that and the first launch in Craig's actual
terminal frame was all black — the dark background-color faces read as black and
the cursor was a GUI-only =:box=, so the whole grid was invisible. The
colored-tiles-are-readable assumption was false in the real environment. A
prototype loop caught it on the first screenshot; had we "built to spec" and
called it done, we'd have shipped an unusable board. The fix (glyphs as the
primary signal, inverse-video cursor) is exactly the kind of adjustment that only
surfaces by looking at the running UI, and it now needs to flow back into the
spec so the build target is the prototype, not the original spec text.

Jotto (the other game spec'd the same day) also has a UI and will follow the same
path.

* Requested action

Fold the rule into the brainstorm skill and the spec-lifecycle rules so it
governs every project's UI features, then re-sync. This proposal is the durable
channel; the two game projects apply it locally in the meantime.