redhat-chai-bot · Nov 6, 2026 · Nov 6, 2026 · Nov 6, 2026 · Nov 6, 2026 · Nov 6, 2026
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -67,3 +67,5 @@ jobs:
       - run: python3 -m unittest discover -s triage/scripts -p 'test_*.py' -v
       - run: python3 -m unittest discover -s skills/report-bug/scripts -p 'test_*.py' -v
       - run: python3 -m unittest discover -s design/scripts -p 'test_*.py' -v
+      - run: python3 -m unittest discover -s ui-design/scripts -p 'test_*.py' -v
+      - run: python3 -m unittest discover -s ux-design/scripts -p 'test_*.py' -v
diff --git a/AGENTS.md b/AGENTS.md
@@ -97,6 +97,8 @@ _shared/
     phase-override-resolution.md  # Project-level phase override lookup and activation
     record-manual-edit.md         # Tier 3 manual-edit attribution (wraps capture recipe)
     render-provenance-footer.md   # Render durable footer into docs-repo markdown before commit
+    screenshot-inspection.md      # Screenshot identity verification and visual inspection (used by ui-design)
+    screenshot-publish-stage.md   # Owned-path allowlist, staging, and commit for screenshot publishes (used by ux-design)
     self-review-gate.md           # Pre-PR self-review quality gate (used by bugfix, implement, e2e, cve-fix)
     validation-gate.md            # Pre-commit build/test/lint discovery gate (used by bugfix)
 ```

diff --git a/_shared/recipes/screenshot-inspection.md b/_shared/recipes/screenshot-inspection.md
diff --git a/_shared/recipes/screenshot-publish-stage.md b/_shared/recipes/screenshot-publish-stage.md
diff --git a/ui-design/README.md b/ui-design/README.md
@@ -36,6 +36,8 @@ graph TD
 | Docs repository (configured) | For `/ingest`, `/publish` | Load upstream PRD, design doc, UX handoff; publish UI design |
 | GitHub CLI (`gh`) | For `/publish`, `/respond` | Create PRs, post review comments |
 | Git | Yes | Branch management, commits |
+| Runtime image-reading capability | For screenshot inspection | Open and inspect image files |
+| Runtime binary-download capability | For external screenshot inspection | Retrieve image bytes from URLs |
 
 ## Inputs
 
@@ -47,6 +49,7 @@ The workflow draws from multiple published sources — never from another workfl
 | Context path | User-provided filesystem path (non-Jira flow only) | No — used when starting from a local document |
 | Description | User-provided text (non-Jira flow only) | No — used when starting from a textual description |
 | UX handoff (`handoff.md`) | Docs repo (from `ux-design` workflow) | No — optional for purely technical work |
+| UX screenshots (`screenshots/` or external URLs) | Docs repo (repo-local files or immutable external HTTPS refs alongside `handoff.md`) | No — present only when evaluation captured screenshots |
 | PRD (`prd.md`) | Docs repo (from `prd` workflow) | Yes |
 | Design document (`design.md`) | Docs repo (from `design` workflow) | Yes |
 | `AGENTS.md` / `UI-ARCHITECTURE.md` | Project root | If available |
@@ -80,6 +83,8 @@ Jira).
 /ui-design:ingest EDM-1234
   → fetches the [UI] story from Jira
   → follows references to load UX handoff, PRD, design doc from docs repo
+  → if UX handoff has screenshots, opens and visually inspects each image
+  → records screenshot observations (visual details, text/image consistency)
   → reads AGENTS.md, UI-ARCHITECTURE.md
   → explores UI codebase (components, hooks, routes, state, tests)
   → explores backend API (types, endpoints, OpenAPI specs)

diff --git a/ui-design/SKILL.md b/ui-design/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ui-design
-version: 0.1.0
+version: 0.2.0
 description: >-
   UI design workflow that takes a [UI] Jira story and optional UX handoff artifact,
   produces a component decomposition with hook design, state management,

diff --git a/ui-design/guidelines.md b/ui-design/guidelines.md
@@ -11,6 +11,12 @@
 - **Persona-aware decomposition is required.** When the UX handoff identifies multiple user groups with distinct views or permissions, the component architecture must address conditional rendering, permission gates, and shared vs. persona-specific components explicitly.
 - **Data annotations drive API review.** Every `Unknown` or `API` source type in the UX handoff's Data Annotations table must be resolved to a specific API endpoint and field — or flagged as a gap.
 - **Accessibility is architectural.** ARIA roles, keyboard navigation, and focus management are designed alongside components, not bolted on later.
+- **Screenshots are visual evidence, not runtime verification.** When UX
+  handoff screenshots are available, cite them for layout and visual-state
+  decisions. Screenshots show rendered presentation; they do not verify
+  keyboard navigation, accessibility compliance, API behavior, or runtime
+  state management. Flag text/image discrepancies rather than silently
+  choosing one source or inventing behavior to reconcile them.
 - **Tests validate behavior, not implementation.** The testing strategy describes what user-facing behaviors to verify, using the project's existing test framework and patterns.
 
 ## Shared Content Rules
@@ -21,6 +27,7 @@ artifacts and published output from this workflow.
 ## Hard Limits
 
 - No fabricated requirements. Every component, hook, and route must trace to a UX handoff element, design document constraint, PRD requirement, or user direction.
+- No fabricated visual observations. When screenshots cannot be inspected (tool unavailability, unreadable files), report the limitation — do not invent observations from captions, alt text, or filenames.
 - No publishing (creating PRs, posting comments) without explicit user approval.
 - No Jira modifications without explicit user approval and a dry-run preview first.
 - **No scope reduction.** Never silently simplify, defer to "v2", use "placeholder", or say "future enhancement" to reduce scope. If scope won't fit, propose a split — don't reduce.