0027: Demote The Visual Almanac To An Optional Product Recipe

Status: Superseded by ADR 0038

Date: 2026-07-21

Context

STAGE corrected an evidence-first visual workflow in several steps. It moved inspection from detached contact sheets into the engine, separated visual questions from asset catalogs, distinguished state sequences from continuous motion, and eventually preferred a product-native Gallery over a parallel Test Lab. Those corrections produced useful lessons and one useful Lanternworks Almanac.

The correction itself then became disproportionate. At this decision point, 73 of STAGE's 201 commits had visual, Almanac, rehearsal, contact, or capture in their subjects. Those commits contained approximately 42,638 additions, 36,611 deletions, and 1,070 file touches. Current guidance devoted 1,658 lines to the generic Visual Review guide, generic Visual Almanac guide, Unity Almanac profile, and two visual skills. The STAGE core specification did not require an Almanac.

This is not evidence that product Galleries are bad. It is evidence that STAGE turned one optional game feature into a peer method, gave it a dedicated skill and vocabulary, and repeatedly refined infrastructure after the useful rule was already known:

Inspect the production consumer in the owning engine. Preserve recurring setup inside a product or developer surface only when somebody actually uses it. Export media only for a named consumer.

Decision

• Keep Visual Review as the sole STAGE visual workflow. It starts with the smallest consumer-complete engine or game route and leaves aesthetic acceptance with the human.
• Retire the standalone stage-visual-almanac skill. The primary visual skill may route a genuinely recurring need to an optional product-gallery recipe.
• Treat Gallery, Almanac, Codex, Bestiary, model viewer, replay browser, world previewer, and inspect mode as project product/tool choices, not STAGE architecture roles or required vocabulary.
• Keep one compact generic recipe and one compact Unity recipe. They describe questions, canonical content, production rendering, truthful time, useful controls, readiness, reset, and teardown without prescribing interfaces or class names.
• Do not require a shared player/developer surface. Reuse one implementation when both jobs are real and compatible; otherwise build only the mode with an actual consumer.
• Do not require a custom driver, manifest, capture plan, contact sheet, or evidence package. Add stable operation or export only when its own repeated consumer earns it.
• Preserve the detailed historical ADRs and trials as research evidence. Mark them as historical or superseded where their terminology would otherwise direct current implementation.

Consequences

• Routine visual work has one entry point and a much smaller instruction load.
• Agents are less likely to answer a visual defect by creating a browser, catalog, scenario architecture, or evidence product.
• A game can still ship a useful Almanac or Gallery and expose developer controls, but the feature follows that game's vocabulary and architecture.
• Existing Lanternworks and Circussy trials remain valid historical evidence; their local names do not become universal STAGE requirements.
• Removing the separate skill is an intentional pre-1.0 interface change with no known external consumer.

Evidence Boundary

The churn measurement is repository evidence, not a controlled productivity study. The decision is additionally informed by direct same-owner rejection of the detached Circussy workflow and successful use of production Route motion in the Lanternworks Almanac. It does not establish that another project should never build a Gallery, visual regression suite, or portable review package. Those remain valid when a named consumer justifies their cost.