author-ux-lens

name	author-ux-lens
description	Author a shaped slice's UX lens as an MD grounding doc — the screens (with low-fidelity layouts), the states each holds, and the product's visual core (color + typography) — from the slice's hub (its functionalities' grounding docs + the spine profile) and KB pattern grounding. Writes the per-node grounding doc ux.md STRAIGHT TO THE LIVE MODEL (conforming to the UX lens template) and emits the visual-core decision plus the grounding map as structured data in a manifest; it NEVER writes a shared model file (the spine _spine.yaml, the profile, or a decisions/*.yaml). Reads the functionality.md docs for the hub, never another lens. Generative artifact production for the /ux play under direct-model-write (ADR 026).
version	0.5.0
user-invocable	false
model	opus
allowed-tools	Read, Write, Bash, Glob

author-ux-lens

Turns a shaped slice's hub — the grounding docs of the functionalities it bundles, plus the product profile — into the slice's UX lens, written as the grounding doc ux.md: the screens that make every functionality visible, the states each screen holds, and the product's visual core. It anchors the intended experience; it is not a full spec. It reads the hub only (never another realize lens).

Write discipline (ADR 026, standards/rules/direct-model-write.md). This skill writes ONLY the per-node doc ux.md, straight to the live model in place. It does NOT write any shared model file — not the spine _spine.yaml, not the profile, and not a decisions/*.yaml. The visual-core decision is emitted as structured data in the manifest (decision_delta); the play's deterministic keyed persist script (persist_ux.py) writes that decision in place, keyed to the slice and skip-if-exists. There is no draft tree.

What it produces (against the locked template)

ux.md conforms to standards/schemas/product-os/grounding/lens/ux.md — H1 # UX Lens, sections Intent, Screens (each: name + low-fidelity layout in prose), States (per screen), Visual core (color + typography direction). It must clear the linter (shape) and the content-quality eval (the play runs both). Alongside the doc it writes a structured ux-manifest.yaml (an STM, non-model artifact) carrying the machine-checkable grounding the prose can't — which screen grounds to which functionality, the visual-core grounding, and the visual-core decision delta for the keyed persist to write.

Input

Field	Required	Description
slice_ref	yes	{domain}/{slice-id} — display reference and the persist key.
slice_file	yes	Path to the live slice record (read-only — for the functionalities list it bundles).
functionality_groundings	yes	Paths to each functionality's functionality.md grounding doc (the hub, resolved by check_ready_slice). Read these for intent/behavior — NOT ice.yaml (retired).
profile	yes	The product profile (from the spine) — conditions + surfaces. Read-only.
kb_search	yes	Path to the KB search script, for pattern grounding.
kb_root	yes	Path to knowledge/, to resolve learning ids.
product_base	yes	Product model root — the LIVE write target (and to reuse an existing visual-core decision).
lens_rel	yes	Relative path of the live lens: product-os/{domain}/slices/{slice}/lens/ux.md. Write ux.md here, in place.
manifest_path	yes	Output path under STM for ux-manifest.yaml (grounding map + decision delta + proposals).
stm_base	yes	From config.

Process

Reasoning (drawing screens, enumerating states, choosing the visual core) is yours. Template conformance, grounding, and coverage are non-negotiable.

1. Read the hub. Load each functionality's functionality.md (its behavior, acceptance, boundary) and the profile box (stage / users / surfaces). Do NOT read any other lens.
2. Draw the screens. For each functionality of the slice, the screen(s) that make it visible — a name and a LOW-FIDELITY layout in prose (regions and what each holds). Every functionality the slice bundles must be visualized by at least one screen (coverage).
3. Enumerate the states. For each screen, the states it can hold (loading, empty, error, partial, populated) and what the user sees in each.
4. Choose the visual core. The color and typography direction — grounded in a KB technology/architecture learning (matched to the product's conditions + surfaces via kb_search), or a recorded KB-learning-gap proposal. If the product already carries a visual-core decision (check under product_base), REUSE it — name it in the manifest and emit NO new decision_delta. Otherwise emit the decision as manifest data for the keyed persist to write (do NOT write the decision file yourself).
5. Write the lens in place + the manifest. Write ux.md to the LIVE lens path (product_base + lens_rel), per the template. Write ux-manifest.yaml to manifest_path (STM) carrying: every screen's grounds → a functionality_ref / persona / journey; the visual core's grounding → kb or the reused decision; and, when a new decision is needed, the decision_delta (id, the slice-scoped rel, and the full record body). Write any KB proposals under an STM proposals folder. Write NO shared model file — never _spine.yaml, never the profile, never a decisions/*.yaml.

Output

LIVE (in place, under product_base):
  product-os/{domain}/slices/{slice}/lens/ux.md            # the UX lens grounding doc (the only live write)

STM (non-model):
  {manifest_path}                                           # ux-manifest.yaml — grounding map + decision delta
  {stm}/proposals/<gap>.yaml                                # KB-learning-gap proposals (only if gaps)

ux-manifest.yaml:

ux:
  slice_ref: token-dash/slice-trusted-coverage
  screens:
    - name: "Source coverage view"
      grounds:
        - { source_type: functionality, source: "func-source-coverage-freshness", functionality_ref: func-source-coverage-freshness }
  design_system:                                  # the visual core grounding
    source_type: decision                         # kb | decision
    decision: dec-visual-core-token-dash
  decision_delta:                                 # OMIT when reusing an existing product decision
    id: dec-visual-core-token-dash
    rel: product-os/token-dash/slices/slice-trusted-coverage/decisions/dec-visual-core-token-dash.yaml
    record:                                       # the full decision YAML body the keyed persist writes
      id: dec-visual-core-token-dash
      level: slice
      status: accepted
      # … dimension, choice, grounding …
  choices: []                                     # KB-grounded pattern choices (visual core / nav / responsive)

Return the enriched contract with the live lens_rel written and the ux-manifest.yaml path — paths, never inline content.

Rules

• Hub only. Derive from the functionalities' grounding docs + the profile; never read or ground on another realize lens.
• Template-true. ux.md conforms to the UX lens template (Intent/Screens/States/Visual core) and must clear the linter + the content eval — every item self-explaining.
• Three things only. Screens, states, visual core. No flows (the build derives them), no accessibility (that is the marketing lens now), no gates/components/environments.
• Cover every functionality. Every functionality the slice bundles is visualized by ≥1 screen, recorded in the manifest.
• Grounded, not invented. Every screen grounds to a functionality or a persona/journey; the visual core grounds to a KB learning or a proposal and is recorded as a decision.
• One live doc; no shared file. Write ONLY ux.md to the live model. The visual-core decision goes into the manifest as decision_delta — the play's keyed persist writes it. Never write _spine.yaml, the profile, or a decisions/*.yaml; never write to another slice.