0018: Escalate Visual Review By Recurring Need

Status: Historical escalation ladder; recurring-utility principle retained; persistent-Almanac step superseded by ADR 0027

Terminology and detached-export consequences are superseded by ADR 0025. The separate capability declaration described below was retired by ADR 0026. Current projects record their native routes in ordinary project maps and operating docs. ADR 0027 removes a persistent Almanac from STAGE's maturity ladder. Custom UI must independently serve a real product, authoring, or development job.

Context

STAGE's first visual workflow made portable captures and a detached contact sheet the center of review. Replacing that with an engine-native Visual Almanac corrected the ownership boundary, but it left another possible overcorrection: building a custom Almanac entry for every asset or visual question.

Game engines already provide useful native inspection surfaces. Asset previews, animation editors, prefab or scene isolation, VFX editors, Game views, and ordinary development routes often answer one-off questions with less lifecycle and maintenance cost than a custom browser. Unreal's animation editors, for example, combine a real viewport, playback, asset browsing, and saved preview scene settings. Unity's Animation window and VFX Graph previews similarly keep asset-local work beside the authored source. A project-owned scenario browser becomes valuable when a question crosses assets or runtime systems, recurs, or needs stable human and agent operation.

The method therefore needs to choose the smallest truthful native surface, not make the Visual Almanac itself a goal.

Decision

Visual work escalates only when the next surface has a named recurring need:

1. Use an existing engine asset editor or preview for an asset-local, one-off question.
2. Use the real development or game route for a one-off question that depends on runtime composition, camera, input, physics, UI, or scene context.
3. Add a Visual Review Scenario to a project-owned Visual Almanac when the question recurs, is costly to reconstruct, crosses several production systems, or benefits from stable named states and human-owned presentation.
4. Add a Native Review Driver when repeated human or agent operation needs a stable callable lifecycle.
5. Add Visual Regression Capture only when a stable visual coordinate is worth maintaining and comparing.
6. Add Evidence Export only for a named remote, durable, CI, milestone, or audit consumer.

A player Codex or Gallery remains a product decision rather than a maturity step. When it has independent player value, ADR 0024 prefers it as the shared runtime home for player presentation and gated developer inspection instead of creating a parallel visual product. Their authority remains distinct even when their subject resolution, staging, rendering, and playback are shared.

When a Visual Review Scenario is justified, its primary workspace presents the live engine view. Named Review Beats or state thumbnails are navigation around that live state, not a substitute contact sheet. Continuous-motion questions must expose genuine playback. Camera, background, lighting, quality, and data fixtures remain human-configurable beside the view, and readiness or invalid content remains visible.

No visual-specific schema is required. The ordinary project map and operating docs record actual project capability; they do not require every project to implement a custom Almanac or every visual question to become a persistent Scenario.

Consequences

• STAGE can improve a one-off visual without first creating infrastructure.
• Custom Almanac work is justified by repeated decision cost rather than asset count or methodological completeness.
• Existing engine editors remain first-class native review surfaces when they answer the question truthfully.
• Scenario workspaces emphasize live motion and immediate presentation tuning; still strips and thumbnails remain optional navigation.
• Automation, regression, and export are added independently and may never be needed by a small project.
• Project maps may honestly report no custom Almanac while recording the native surfaces a project actually uses.