0038: Treat Visual Galleries As Ordinary Project Features

Status: Accepted; dedicated visual-skill portion superseded by ADR 0048

Date: 2026-07-22

Context

ADR 0027 correctly demoted STAGE's Visual Almanac from a peer workflow to an optional recipe. The repository nevertheless retained a 166-line generic gallery recipe, a 172-line Unity recipe, map vocabulary, authoring-surface entries, and tests dedicated to that recipe structure.

This preserved the wrong ownership boundary. A useful codex, bestiary, model viewer, world previewer, almanac, or inspect mode is a game or project-tool feature. It should exist because a player, author, or recurring developer uses it, and it should be designed through that project's normal backlog, architecture, input, lifecycle, and acceptance process. Its incidental value for visual inspection does not make it a STAGE capability.

The Circussy visual-workflow dogfood made the distinction concrete. Detached captures and contact sheets were technically operable but low-value. A native motion preview was useful because it exposed real content and continuous production behavior. The owner's stronger conclusion was that a genuinely useful persistent surface should have been part of the game or editor, such as an almanac or gallery, rather than a separate rehearsal product.

Decision

• Retain Visual Review as bounded inspection through the smallest consumer-complete native surface.
• Remove the generic and Unity gallery recipe documents from active STAGE.
• Preserve their useful safeguards in the Visual Review guide and Unity profile: canonical content, production rendering and motion, human-editable controls, visible readiness failures, complete input paths, reset, teardown, and presentation-boundary verification.
• Treat a codex, gallery, bestiary, model viewer, replay browser, world previewer, or inspect mode as an ordinary project feature. Deliver it through the normal change workflow when its own user and value justify it.
• Do not list such features as STAGE optional capabilities, authoring surfaces, maturity steps, artifact families, or universal architecture roles.
• A project-owned feature may be reused for visual inspection only for claims whose production consumers and context it actually contains.
• Keep the then-current dedicated stage-visual-review skill explicit-only for bounded diagnosis. ADR 0048 later removed that route and folded its remaining safeguards into ordinary change delivery.
• Preserve historical ADRs and trials as evidence of the correction path.

Consequences

• Active visual guidance has one conceptual owner instead of a review guide plus two gallery recipes.
• Agents are less likely to answer repeated visual work by inventing a STAGE subsystem or evidence product.
• Games remain free to build useful native galleries, but their domain, architecture, UX, and maintenance follow actual project needs.
• Gallery-specific implementation advice is no longer a method interface. The compact safeguards retained in Visual Review apply equally to any project feature reused for inspection.
• ADR 0027 is superseded where it retained optional STAGE gallery recipes; its historical analysis remains valid.

Evidence Boundary

This decision is based on same-owner dogfood, repository instruction-load measurement, and direct rejection of the detached workflow. It does not prove that galleries, visual regression suites, screenshots, or remote review systems are broadly ineffective. It limits STAGE's ownership claim: those capabilities must be justified and owned by their actual project or external consumer.