Sigil: UX Lessons

• the lesson schema,
• the ux-pattern schema,
• the two consumer adapters (emit-validator, emit-studio),
• the promotion honesty gate.

It COMPOSES (never re-implements) these owners:

Concern	Owner (composed)
session signal capture	signal-observer / observed-invocation-loop
session → analysis shape	workflow-reflect (shape borrowed)
lesson → pattern reduction	distill
reusable pattern store mechanics	architecture-pattern-inventory (cards under a ux tag)
residue ledger	residuality-spec

It NEVER: runs Playwright validation (that is ux-evidence-validator), or mutates studio sessions / generates variants (that is ui-prototyping-studio). UX Lessons emits cards and intents; the consumers own execution.

emit-studio-fitness is PARKED. The mapping is designed and falsification-tested (development/refinement-runs/2026-06-23-ux-lessons-w8-studio-fitness/RESULT.md) but not built. Un-park only when ui-prototyping-studio ships a per-candidate axe/layout evaluator in the cycle AND resolves OQ-5 (soft-score weights). Until then it emits nothing.

lesson_id:               # kebab id, e.g. L-xray-02
session_ref:             # pointer to the session (path / run-id / signal ref)
context:                 # what was being built and for whom
iteration_step:          # which move in the session
trigger:                 # what prompted the change
failure_mode:            # the problem the change fixed
change:                  # what was done
before_after:
  before_ref:            # artifact/screenshot before
  after_ref:             # artifact/screenshot after
  screenshot_refs: []    # evidence images
evidence: []             # enum-constrained, see below
signal_strength:         # anecdote | repeated | cross_session
generalizable_principle: # the reusable claim
residue:                 # what is unresolved / parked
promoted_to:             # pattern_id | null

Evidence enum (evidence[] values must be one of) — the replayable shapes ux-evidence-validator already consumes: dom_measurement | aria_snapshot | screenshot_diff | trace_event.

Honesty rule: signal_strength: anecdote ⇒ promoted_to may NOT target a validator hard_gate. Anecdote lessons can feed soft_flag / screenshot_review only.

pattern_id:              # kebab id, e.g. detail-beside-the-subject
name:
intent:
problem:
solution:
when_to_use:
anti_pattern:
forces: []
evidence_link:           # lesson_id(s) + evidence refs
status:                  # seed | calibrated | promoted
residue:
consumer_intake:
  validator:             # one or more
    - claim_class:       # hard_gate | soft_flag | screenshot_review | human_study | not_automatable
      mode:              # ux-evidence-validator mode entered, e.g. spec
      feeds_field:       # the exact validator field/claim this feeds
  studio:
    intent:              # e.g. reposition | reword | restructure
    comment_event_template:   # CommentEvent shape
    mutation_task:            # MutationTask shape

Anti-overbuild guard: a consumer_intake entry may only assert a check if it names the exact consumer field it feeds. No speculative fields.

• a UI iteration session produced changes worth keeping as reusable lessons,
• a recurring UX move should become a named, evidence-linked pattern,
• a pattern should be handed to ux-evidence-validator as validator-safe claims,
• a pattern should be handed to ui-prototyping-studio as annotation intents,
• prior-session residue should be recovered and deduplicated into patterns.

• you want to run browser validation now (use ux-evidence-validator),
• you want to generate or mutate UI variants now (use ui-prototyping-studio),
• the input is generic workflow telemetry, not UX iteration (use workflow-reflect),
• you need a generic pattern store unrelated to UX (use architecture-pattern-inventory),
• there is no session evidence — patterns may not be invented without a lesson.

• a session reference (path, run-id, or signal ref) for capture,
• existing lesson records for distill,
• a ux-pattern id for promote / emit-*,
• the target consumer for emit-*,
• screenshot / evidence artifacts.

• write typed lesson / ux-pattern artifacts that conform to the schemas,
• keep evidence[] within the enum,
• enforce the anecdote → no-hard-gate honesty rule,
• name the exact consumer field every consumer_intake entry feeds,
• compose the five owners rather than re-implementing them,
• never run validation or mutate studio sessions,
• store patterns as ux-tagged inventory cards, not a new store,
• keep a ux-pattern at seed until usage evidence supports promotion,
• emit an observability signal for meaningful executions.

• inventing a ux-pattern with no backing lesson,
• promoting an anecdote-signal pattern to a validator hard gate,
• adding consumer_intake fields that name no consumer field,
• forking a second reusable-pattern store instead of using architecture-pattern-inventory,
• re-implementing session capture, distillation, or residue mechanics owned elsewhere,
• shipping the studio variant/fitness intake before its named unblock (OQ-5 + fitness evaluator),
• claiming promotion readiness without experiment-harness evidence.

Recommended signal fields: sigil name, mode, lessons captured, patterns distilled, pattern status changes, honesty-rule enforcements, consumer emitted, blocked reasons, reflection trigger state.

• ≥2 sessions captured into lessons with honest signal tagging,
• ≥1 ux-pattern distilled and emitted to BOTH consumers with zero invented fields,
• the anecdote → no-hard-gate rule enforced at least once,
• cross-session promotion (anecdote → repeated → cross_session) demonstrated,
• the validator claim map ingested by ux-evidence-validator --mode spec,
• the studio annotation intent validated against ui-prototyping-studio SPEC.

## UX Lessons Result

- Mode: capture | distill | promote | emit-validator | emit-studio
- Session/pattern ref: <ref>
- Lessons captured: <n or n/a>
- Pattern: <pattern_id and status, or n/a>
- Honesty rule: enforced | not-triggered
- Consumer emitted: ux-evidence-validator | ui-prototyping-studio | none
- Composed owners touched: <list>
- Evidence boundary: <source vs inference note>
- Status: pass | flag | block
- Next: <recommended next mode or route>