ORA

Doctrine

ORA-2026-0051: Design-review gate for UI-facing work

ID
ORA-2026-0051
Date
2026-04-25
Status
ratified
Maturity
M2
Source
docs/entries/doctrines/ORA-2026-0051_design-review-gate-for-ui-facing-work.md

productdesign-systemdesign-reviewui

ORA-2026-0051: Design-review gate for UI-facing work

Rule

Any ticket that changes a user-visible surface (UI component, page layout, data displayed to end users, notification content) MUST include a design intent and a design-review proof before DONE.

Design intent (before work starts)

The ticket or claiming post MUST state the design intent in one paragraph:

  • What the user sees after this change
  • Where it appears (which view, which context)
  • Scoping rule — what data is included and what is excluded

Example (good): "Jobsite photos appear as cards in the SMS thread of the contact who sent/received the photo. Photos NOT sent by or to a specific contact do not appear in their thread."

Example (bad): "Add photo cards to threads."

If the ticket was filed without a design intent, the claiming seat MUST write one before starting code. If the intent is ambiguous, escalate to Chad for a one-sentence clarification rather than guessing.

Design-review proof (before DONE)

The DONE post for UI-facing work MUST include:

DESIGN-REVIEW:
  intent: <one-line restatement of what the user should see>
  screenshot: <path or inline description of end-user-visible result>
  matches-intent: YES | NO (explain)

If matches-intent: NO, the ticket is not DONE — it is IN_PROGRESS with the gap described.

What counts as UI-facing

  • Any HTML/CSS/JS/SwiftUI change that renders in a browser or app
  • Any data change that alters what appears on a user-visible surface
  • Any notification, email, or message content change

What does NOT require this gate

  • Backend-only changes (API, DB, pipeline) with no user-visible effect
  • Infrastructure (deploy, CI, config) changes
  • ORA/doctrine/feed artifacts

Evidence

CMB-1357 (2026-04-25): Codex shipped "jobsite photo cards in SMS threads" to Redline Mac. The implementation broadcast every photo into ALL contact threads instead of attributing photos to the correct thread. The same photo (UUID 310a3768-d7c0-4e72-88d0-aa67bf4d1b05) appeared in Lou Winship, Jimmy Chastain, AND Blanton Winship threads simultaneously.

Root cause: no design intent was stated. The ticket said "add photos" — nobody specified which threads get which photos. The implementing seat made the simplest choice (show all photos in all threads) because no scoping rule existed.

A one-paragraph design intent ("photos appear in the thread of the contact they belong to") would have prevented this. The design-review screenshot would have caught it: "intent says per-contact, screenshot shows all-threads — matches-intent: NO."

Relationship to prior doctrine

  • Extends ORA-2026-0029 (dying-well): adds design-review bullet to DONE

    • checklist for UI-facing work.

  • Complements ORA-2026-0046 (deliverable reachability): that doctrine

    • proves files exist; this doctrine proves UI changes match their intent.

  • Strengthens the "screenshot is the truth bar" feedback: screenshots

    • are now compared against a stated intent, not just taken as existence proof.