ai-sdlc-ux: Traceable Experience Specification

Optional domain skill, not required by the core module. Every rule below is important to follow. None of it can be skipped. UX artifacts specify behavior; they do not imply stakeholder approval or visual fidelity.

0. Skill Card

• Skill name:

  ai-sdlc-ux

• Primary audience: UX, BA, PM
• Supporting audience: Dev, QA, Accessibility, Delivery
• Audience tags: UX, BA, PM, Dev, QA
• SDLC stage: Discovery, refinement, and design
• Purpose: Preserve testable journeys, states, recovery, and accessibility.
• Output:

  ux-spec.md

  and

  _ai_sdlc/ux-spec.toon

0.1 Required Inputs

• Owning feature root.
• UX input using

  ai-sdlc-ux-input/v1

  .
• Actors and requirement or acceptance trace targets.

0.2 Clarification Rules

• Ask when actor, goal, permission, channel, or success outcome is ambiguous.
• Separate user need from interface solution and visual preference.
• Include non-happy states and recovery behavior, not only a golden path.
• Do not infer accessibility conformance or user research evidence.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Quick flow permits one traced actor journey with explicit gaps.
• Full flow requires at least one journey, interaction state, and accessibility check.
• Both modes require exact trace targets and actor consistency.

0.3 Output Rules

• Return actors, journey/state coverage, accessibility status, blockers, and output paths directly in the Codex response.
• Before the final response, emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; every action includes

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or untraced mockup prose.
• Keep behavior testable and avoid presenting assumptions as research.

0.4 Artifact Routing

• Write

  <feature-root>/ux-spec.md

  .
• Write

  <feature-root>/_ai_sdlc/ux-spec.toon

  .
• Use the owning workspace selected by the feature; implementation UX supports SDD.
• Keep generated image/design files separate and link them as evidence when present.

0.5 Feature State Machine

• Read

  <feature-root>/_ai_sdlc/state.toon

  before durable work.
• UX is an optional capability and does not add a core lifecycle stage.

• --state-check

  is read-only;

  --begin-state

  and

  --complete-state

  are rejected.
• Route accepted behavior changes through owning requirements and change-impact workflows.

0.6 Artifact Metadata And Metatags

• Markdown starts with

  artifact_metadata

  using schema

  ai-sdlc-ux-metadata/v1

  .
• Include

  metatags

  for

  ai-sdlc

  ,

  ux

  ,

  experience

  , and

  traceable

  .
• Record feature, workspace, flow mode, state file, trace IDs, and review status.

0.7 Specs Index

• Read the relevant

  specs/_ai_sdlc/specs-index.toon

  or

  specs-refiniment/_ai_sdlc/specs-index.toon

  before broad reads.
• Refresh the matching

  specs/specs-index.md

  or

  specs-refiniment/specs-index.md

  only after durable writes.
• Keep one UX artifact in the owning feature boundary.

References

• Read

  references/ux-contract.md

  for actor, journey, state, and accessibility fields.
• Use

  scripts/ux.py

  to validate and route the canonical artifact pair.

Script Usage

python3 skills/ai-sdlc-ux/scripts/ux.py specs-refiniment/onboarding --input /tmp/ux.json --emit --quick-flow
python3 skills/ai-sdlc-ux/scripts/ux.py specs/onboarding --input /tmp/ux.json --write --full-flow --format toon

Purpose

Inputs

• Define stable actor IDs, goals, and needs.
• Trace every journey, state, and accessibility check.
• Make steps ordered and acceptance outcomes observable.
• Cover recovery from failure and blocked user states.

Steps

1. Read customer/problem evidence, requirements, actors, and constraints.
2. Define actors and their goals without inventing research claims.
3. Map end-to-end journeys with ordered steps and acceptance outcomes.
4. Specify loading, empty, error, permission, success, and recovery states.
5. Define accessibility requirements and evidence status.
6. Finalize routed Markdown and TOON outputs.
7. Route behavior changes to BA/SDD and test cases.

Output Spec

ai-sdlc-ux/v1

• Pass when journey actors exist, steps and acceptance are observable, states include behavior plus recovery, and accessibility status has evidence.
• Full flow fails without journey, state, or accessibility coverage.

Examples

ACT-001

AC-012

Edge Cases

• One actor may have several journeys with different permissions or channels.
• A state may intentionally have no recovery; document the reason explicitly.
• Accessibility checks may be planned, passed, failed, or blocked.
• Visual references remain optional evidence and never replace behavior contracts.

Scope Boundary

• Do not claim user validation without research evidence.
• Do not generate production UI code unless separately requested through SDD.
• Do not replace business rules, requirements, or test cases.
• Do not mark accessibility conformance from intent alone.
• Use

  $ai-sdlc-change-impact

  when accepted UX behavior invalidates downstream work.