From 7a1ceb06cd562b1579e989ac2b2849e0f256e0b5 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 21 Aug 2026 14:33:55 -0400 Subject: [PATCH 01/15] Add /ux-design workflow with research, prototyping, evaluation, and handoff MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the ux-design workflow: ingest → research → prototype → evaluate → handoff → revise → publish → respond. Produces a structured handoff artifact (05-handoff.md) containing component mapping, interaction specs, state enumeration, data annotations, persona-specific views, and acceptance criteria for consumption by the planned ui-design workflow. Key design decisions: - /research is a conditional phase (skippable when researcher has data) - External uxd-workshop skills are optional enrichments, not primary paths, to ensure artifact structure is always consistent for downstream phases - install.sh installs uxd-workshop skills via a single generic path (git clone + symlinks) for all AI tools; scoped to ux-design installs only Based on work from PR #102 by jpuzzo@redhat.com. Co-authored-by: Joe Puzzo Assisted-by: Claude claude-sonnet-4-6[1m] --- AGENTS.md | 2 + README.md | 3 + install.sh | 40 ++++++ ux-design/README.md | 168 +++++++++++++++++++++++ ux-design/SKILL.md | 26 ++++ ux-design/commands/evaluate.md | 11 ++ ux-design/commands/handoff.md | 11 ++ ux-design/commands/ingest.md | 11 ++ ux-design/commands/prototype.md | 11 ++ ux-design/commands/publish.md | 11 ++ ux-design/commands/research.md | 11 ++ ux-design/commands/respond.md | 11 ++ ux-design/commands/revise.md | 11 ++ ux-design/guidelines.md | 67 +++++++++ ux-design/skills/controller.md | 226 ++++++++++++++++++++++++++++++ ux-design/skills/evaluate.md | 220 +++++++++++++++++++++++++++++ ux-design/skills/handoff.md | 236 ++++++++++++++++++++++++++++++++ ux-design/skills/ingest.md | 121 ++++++++++++++++ ux-design/skills/prototype.md | 163 ++++++++++++++++++++++ ux-design/skills/publish.md | 180 ++++++++++++++++++++++++ ux-design/skills/research.md | 164 ++++++++++++++++++++++ ux-design/skills/respond.md | 130 ++++++++++++++++++ ux-design/skills/revise.md | 78 +++++++++++ 23 files changed, 1912 insertions(+) create mode 100644 ux-design/README.md create mode 100644 ux-design/SKILL.md create mode 100644 ux-design/commands/evaluate.md create mode 100644 ux-design/commands/handoff.md create mode 100644 ux-design/commands/ingest.md create mode 100644 ux-design/commands/prototype.md create mode 100644 ux-design/commands/publish.md create mode 100644 ux-design/commands/research.md create mode 100644 ux-design/commands/respond.md create mode 100644 ux-design/commands/revise.md create mode 100644 ux-design/guidelines.md create mode 100644 ux-design/skills/controller.md create mode 100644 ux-design/skills/evaluate.md create mode 100644 ux-design/skills/handoff.md create mode 100644 ux-design/skills/ingest.md create mode 100644 ux-design/skills/prototype.md create mode 100644 ux-design/skills/publish.md create mode 100644 ux-design/skills/research.md create mode 100644 ux-design/skills/respond.md create mode 100644 ux-design/skills/revise.md diff --git a/AGENTS.md b/AGENTS.md index 6c360f66..9a5c70dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ This repository contains reusable AI coding workflows that can be installed glob - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond) - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff) - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond) +- **ux-design** — UX design workflow (ingest, research, prototype, evaluate, handoff, revise, publish, respond) - **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push) - **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply) - **skill-reviewer** — Meta-workflow that audits AI skill directories @@ -168,6 +169,7 @@ ai-workflows/ │ ├── prompts/ │ └── scripts/ ├── triage/ +├── ux-design/ ├── install.sh # Installer with auto-discovery ├── uninstall.sh # Removal script ├── AGENTS.md # AI assistant guidance (this file) diff --git a/README.md b/README.md index b6b5dbd7..8e4dc622 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,9 @@ Reusable AI coding workflows a team member can install globally or per-project, - **Skill Reviewer** -- Meta-workflow that audits AI skill directories against eight quality dimensions. See [skill-reviewer/README.md](skill-reviewer/README.md). +- **UX Design** -- UX design workflow: ingest a feature request, conduct user research, generate prototypes, run heuristic evaluation, and produce a validated design handoff for the `ui-design` workflow. + See [ux-design/README.md](ux-design/README.md). + ## How It Works Each workflow is a directory with a `SKILL.md` (the mandatory entry point), optional phase skills under `skills/`, and optional command wrappers under `commands/` -- all plain markdown, no IDE-specific syntax. Some workflows also include a `skills/controller.md` for phase dispatch, but this is an optional pattern. The installer auto-discovers every directory that contains a `SKILL.md`. diff --git a/install.sh b/install.sh index 1bc2c953..05709eb8 100755 --- a/install.sh +++ b/install.sh @@ -131,6 +131,43 @@ ensure_repo_linked() { echo " Linked $INSTALL_DIR -> $REPO_DIR" } +UXD_REPO="https://github.com/rh-uxd/ai-helpers.git" +UXD_DIR="${HOME}/.uxd-ai-skills" +UXD_PLUGINS=(uxd-workshop) + +# Install UXD AI Skills via git clone + symlinks (AI-agnostic; works for all +# tools). Called at the end of each install target when ux-design is in scope. +install_uxd_skills() { + local skills_dir="$1" + + # Only install if ux-design is in the workflow set being installed + local has_ux_design=false + for wf in "${WORKFLOWS[@]}"; do + [[ "$wf" == "ux-design" ]] && has_ux_design=true + done + "$has_ux_design" || return 0 + + if [[ ! -d "$UXD_DIR" ]]; then + echo " Cloning UXD AI Skills repo..." + git clone --depth 1 "$UXD_REPO" "$UXD_DIR" 2>/dev/null || { + echo " Warning: could not clone UXD AI Skills repo; ux-design optional skills unavailable" >&2 + return 0 + } + fi + + for plugin in "${UXD_PLUGINS[@]}"; do + local plugin_skills="${UXD_DIR}/plugins/${plugin}/skills" + [[ -d "$plugin_skills" ]] || continue + for skill_dir in "${plugin_skills}"/*/; do + [[ -d "$skill_dir" ]] || continue + local skill_name + skill_name="$(basename "$skill_dir")" + ln -sfn "$skill_dir" "${skills_dir}/${skill_name}" + echo " Linked ${skills_dir}/${skill_name} -> ${skill_dir} (uxd)" + done + done +} + install_shared() { local target_dir="$1" if [[ ! -d "${INSTALL_DIR}/_shared" ]]; then @@ -203,6 +240,7 @@ install_cursor() { echo " Linked ${SKILLS_DIR}/${wf} -> ${INSTALL_DIR}/${wf} ($SCOPE)" done generate_cursor_commands "$CMDS_DIR" + install_uxd_skills "$SKILLS_DIR" } install_claude() { @@ -277,6 +315,7 @@ install_claude() { echo " Removed stale commands symlink ${CMDS_DIR}/${wf} ($SCOPE)" fi done + install_uxd_skills "$SKILLS_DIR" } install_gemini() { @@ -292,6 +331,7 @@ install_gemini() { ln -sfn "${INSTALL_DIR}/${wf}" "${SKILLS_DIR}/${wf}" echo " Linked ${SKILLS_DIR}/${wf} -> ${INSTALL_DIR}/${wf} ($SCOPE)" done + install_uxd_skills "$SKILLS_DIR" } # Offer a daily systemd --user notifier (Linux desktop). Default: no. diff --git a/ux-design/README.md b/ux-design/README.md new file mode 100644 index 00000000..e38c76cb --- /dev/null +++ b/ux-design/README.md @@ -0,0 +1,168 @@ +# UX Design Workflow + +A UX design workflow that takes a feature request through discovery, user +research, prototyping, and heuristic evaluation to produce a validated +design handoff artifact for the `ui-design` workflow. + +## Phase Flow + +```mermaid +graph TD + ingest([ingest]) --> research + ingest --> prototype + research --> prototype + prototype --> evaluate + evaluate -->|iterate| prototype + evaluate -->|ready| handoff + handoff --> revise + handoff --> publish + revise --> publish + publish --> respond +``` + +Research is conditional — skip directly to `/prototype` if the researcher +already has validated data or well-understood user needs. + +## Prerequisites + +| Tool | Required | Purpose | +|------|----------|---------| +| Jira access (MCP or CLI) | For `/ingest` | Fetch issue details for problem framing | +| UXD marketplace plugins | Optional | Enhances `/ingest`, `/prototype`, `/evaluate`, `/handoff` | + +## Phases + +| Phase | Command | Purpose | Artifact(s) | +|-------|---------|---------|-------------| +| Ingest | `/ingest` | Frame the problem, identify user groups, survey landscape | `01-discovery.md` | +| Research | `/research` | Conduct user research, synthesize findings | `02-research.md` | +| Prototype | `/prototype` | Generate design prototypes from research | `03-prototype/` | +| Evaluate | `/evaluate` | Heuristic evaluation and usability assessment | `04-evaluation.md` | +| Handoff | `/handoff` | Produce implementation-ready design spec | `05-handoff.md` | +| Revise | `/revise` | Incorporate stakeholder feedback | `05-handoff.md` (updated) | +| Publish | `/publish` | Push handoff spec to docs repo for review | PR in docs repo | +| Respond | `/respond` | Address PR reviewer comments | Updated `05-handoff.md` | + +## Typical Flow + +```text +/ingest EDM-1234 + → frames the problem, identifies user groups + → surveys competitive landscape + → writes .artifacts/ux-design/EDM-1234/01-discovery.md + +/research (conditional — skip if you have data) + → conducts user research + → synthesizes findings into themed insights + → documents persona-specific needs + → writes 02-research.md + +/prototype + → generates design prototypes informed by research + → writes 03-prototype/ (files + prototype-notes.md) + +/evaluate + → runs heuristic evaluation against prototype + → writes 04-evaluation.md + → loops back to /prototype if critical issues found + +/handoff + → synthesizes all artifacts into implementation spec + → maps UI elements to design system components + → annotates data requirements per UI element + → documents persona-specific views + → writes 05-handoff.md + +/publish + → pushes 05-handoff.md to docs repo + → opens PR for team review + +/respond + → addresses PR review comments + → updates 05-handoff.md as needed +``` + +## Artifacts + +All artifacts are stored in `.artifacts/ux-design/{issue-key}/`. + +```text +.artifacts/ux-design/EDM-1234/ + 01-discovery.md (problem framing, user groups, landscape) + 02-research.md (research findings, insights, recommendations) + 03-prototype/ (prototype files, design rationale) + prototype-notes.md (design decisions, user stories covered) + 04-evaluation.md (heuristic eval report, readiness assessment) + 05-handoff.md (implementation spec, component mapping, AC) +``` + +## Handoff Contract + +`05-handoff.md` is the primary artifact consumed by the `ui-design` workflow. +It contains: + +- **Component mapping** — UI elements mapped to design system components +- **Interaction specs** — every user interaction documented +- **State enumeration** — empty, loading, error, populated, responsive +- **Data annotations** — what data each UI element needs (with gaps flagged) +- **Persona-specific views** — where user groups interact differently +- **Acceptance criteria** — testable, traced to research findings +- **Research context** — why decisions were made + +## UXD Marketplace Skills + +This workflow optionally uses skills from the +[UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). +All phases function without them — the skills enhance output quality +but are not required. + +| Skill | Plugin | Used by | +|-------|--------|---------| +| `uxd-discovery` | `uxd-workshop` | `/ingest` | +| `uxd-prototype-create` | `uxd-workshop` | `/prototype` | +| `uxd-figma-read` | `uxd-workshop` | `/prototype` | +| `uxd-research-heuristic-eval` | `uxd-workshop` | `/evaluate` | +| `uxd-evaluate-design-heuristics` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` | +| `uxd-design-handoff` | `uxd-workshop` | `/handoff` | + +## Directory Structure + +```text +ux-design/ +├── SKILL.md # Workflow entry point +├── guidelines.md # Behavioral rules and guardrails +├── README.md # This file +├── skills/ +│ ├── controller.md # Phase dispatcher and transitions +│ ├── ingest.md # Frame problem, identify user groups +│ ├── research.md # Conduct user research +│ ├── prototype.md # Generate design prototypes +│ ├── evaluate.md # Heuristic evaluation +│ ├── handoff.md # Design-to-implementation spec +│ ├── revise.md # Incorporate stakeholder feedback +│ ├── publish.md # Push to docs repo PR +│ └── respond.md # Address PR review comments +└── commands/ + ├── ingest.md # /ingest command + ├── research.md # /research command + ├── prototype.md # /prototype command + ├── evaluate.md # /evaluate command + ├── handoff.md # /handoff command + ├── revise.md # /revise command + ├── publish.md # /publish command + └── respond.md # /respond command +``` + +## Getting Started + +```bash +# Install the workflow +./install.sh claude --workflows ux-design + +# Or install all workflows +./install.sh all +``` + +Then in your project, run `/ingest` with a Jira issue key or feature +description to begin. diff --git a/ux-design/SKILL.md b/ux-design/SKILL.md new file mode 100644 index 00000000..d0e4b593 --- /dev/null +++ b/ux-design/SKILL.md @@ -0,0 +1,26 @@ +--- +name: ux-design +version: 0.1.0 +description: >- + UX design workflow that takes a feature request through discovery, + prototyping, and heuristic evaluation to produce a validated design + handoff artifact for implementation. + Useful for creating prototypes for evaluation, running heuristic + evaluations, or preparing design handoffs. + Activated by commands: /ingest, /research, /prototype, /evaluate, /handoff, /revise, /publish, /respond. +--- +# UX Design Workflow Orchestrator + +## Quick Start + +1. If the user invoked a specific command (e.g., `/prototype`, `/evaluate`), + read `commands/{command}.md` and follow it. +2. Otherwise, read `skills/controller.md` to load the workflow controller: + - If the user provided a Jira issue key or URL, execute the `/ingest` phase + - Otherwise, execute the first phase the user requests + +If a step fails or produces unexpected output, stop and report the error to +the user. Do not advance to the next phase. Offer to retry the failed step or +escalate. + +For principles, hard limits, and escalation rules, see `guidelines.md`. diff --git a/ux-design/commands/evaluate.md b/ux-design/commands/evaluate.md new file mode 100644 index 00000000..36717d0f --- /dev/null +++ b/ux-design/commands/evaluate.md @@ -0,0 +1,11 @@ +--- +name: ux-design:evaluate +description: "Run heuristic evaluation and usability assessment against prototypes" +--- +# /evaluate + +Read `../skills/controller.md` and follow it. + +Dispatch the **evaluate** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/handoff.md b/ux-design/commands/handoff.md new file mode 100644 index 00000000..bcc1747d --- /dev/null +++ b/ux-design/commands/handoff.md @@ -0,0 +1,11 @@ +--- +name: ux-design:handoff +description: "Synthesize all research into an implementation-ready handoff spec" +--- +# /handoff + +Read `../skills/controller.md` and follow it. + +Dispatch the **handoff** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/ingest.md b/ux-design/commands/ingest.md new file mode 100644 index 00000000..94fec413 --- /dev/null +++ b/ux-design/commands/ingest.md @@ -0,0 +1,11 @@ +--- +name: ux-design:ingest +description: "Frame the problem, identify user groups, and survey the competitive landscape" +--- +# /ingest + +Read `../skills/controller.md` and follow it. + +Dispatch the **ingest** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/prototype.md b/ux-design/commands/prototype.md new file mode 100644 index 00000000..a33cfc1b --- /dev/null +++ b/ux-design/commands/prototype.md @@ -0,0 +1,11 @@ +--- +name: ux-design:prototype +description: "Generate design prototypes informed by research findings" +--- +# /prototype + +Read `../skills/controller.md` and follow it. + +Dispatch the **prototype** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/publish.md b/ux-design/commands/publish.md new file mode 100644 index 00000000..e33088cb --- /dev/null +++ b/ux-design/commands/publish.md @@ -0,0 +1,11 @@ +--- +name: ux-design:publish +description: "Push the handoff spec as a GitHub PR for external review" +--- +# /publish + +Read `../skills/controller.md` and follow it. + +Dispatch the **publish** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/research.md b/ux-design/commands/research.md new file mode 100644 index 00000000..277d60d8 --- /dev/null +++ b/ux-design/commands/research.md @@ -0,0 +1,11 @@ +--- +name: ux-design:research +description: "Conduct user research, gather data, and synthesize findings into insights" +--- +# /research + +Read `../skills/controller.md` and follow it. + +Dispatch the **research** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/respond.md b/ux-design/commands/respond.md new file mode 100644 index 00000000..45468bbf --- /dev/null +++ b/ux-design/commands/respond.md @@ -0,0 +1,11 @@ +--- +name: ux-design:respond +description: "Fetch and address reviewer comments on the handoff spec PR" +--- +# /respond + +Read `../skills/controller.md` and follow it. + +Dispatch the **respond** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/revise.md b/ux-design/commands/revise.md new file mode 100644 index 00000000..aee8d5b0 --- /dev/null +++ b/ux-design/commands/revise.md @@ -0,0 +1,11 @@ +--- +name: ux-design:revise +description: "Incorporate stakeholder feedback into the handoff spec" +--- +# /revise + +Read `../skills/controller.md` and follow it. + +Dispatch the **revise** phase. Context: + +$ARGUMENTS diff --git a/ux-design/guidelines.md b/ux-design/guidelines.md new file mode 100644 index 00000000..328ebce7 --- /dev/null +++ b/ux-design/guidelines.md @@ -0,0 +1,67 @@ +# UX Design Workflow Guidelines + +## Principles + +- The researcher drives the process. The AI assists with synthesis, generation, + and evaluation — it does not make research decisions autonomously. +- Every design decision must trace to research findings. Do not invent user + needs or fabricate evidence. +- **Evidence over assumption.** When research data is unavailable, say so + explicitly. "We don't have data on this" is valuable. +- Preserve the researcher's terminology and domain language. Do not rewrite + their findings into generic UX jargon. +- Prototypes are conversation starters, not final designs. A rough prototype + the researcher can react to is more valuable than a polished one they can't. +- Heuristic evaluation supplements — never replaces — real user testing. + AI-driven evaluation catches systematic issues; only humans catch context- + dependent usability problems. Heuristic and simulated evaluation inform + design iteration but do not constitute usability validation. The handoff + spec must note evaluation method and flag when real user testing has not + been conducted. + +## Hard Limits + +- No auto-advancing between phases. Always wait for the researcher. +- No fabricated research findings. Every insight must trace to data the + researcher provided or desk research the AI performed with citations. +- No storing PII in artifacts. User interview data should be anonymized + before inclusion. +- No publishing prototypes or artifacts without explicit researcher approval. +- No skipping the human gate between phases. Present findings, get confirmation. + +## Safety + +- Show your work before finalizing. After each phase, present artifacts for + review — do not assume they're ready. +- Flag assumptions explicitly. If research data doesn't cover something and + you filled it in, mark it as an assumption. +- Indicate confidence levels on recommendations. Distinguish between findings + backed by multiple data sources and single-source observations. + +## Quality + +- Artifacts should be structured for both human reading and machine + consumption. Use consistent markdown with headings. +- Handoff artifacts must be detailed enough for a developer to implement + without additional design consultation. +- Heuristic evaluation findings must include severity ratings and specific + remediation guidance. + +## Escalation + +Stop and request human guidance when: + +- Research reveals contradictory user needs with no clear resolution +- The scope appears too broad for a single research cycle (suggest splitting) +- Prototype feedback is ambiguous or contradictory +- Heuristic evaluation reveals critical accessibility violations that may + require architectural changes +- The researcher's domain expertise is needed to interpret data + +## Working With the Project + +This workflow gets deployed into different projects. Respect the target project: + +- Read and follow the project's own `AGENTS.md` or `CLAUDE.md` files +- Adopt the project's conventions for document formatting if they exist +- Use the project's design system and component library for prototyping diff --git a/ux-design/skills/controller.md b/ux-design/skills/controller.md new file mode 100644 index 00000000..902f9018 --- /dev/null +++ b/ux-design/skills/controller.md @@ -0,0 +1,226 @@ +--- +name: controller +description: Top-level workflow controller that manages phase transitions for UX design — discovery, user research, prototyping, evaluation, handoff, revision, publication, and review response. +--- + +# UX Design Workflow Controller + +You are the workflow controller. Your job is to manage the ux-design workflow +by executing phases and handling transitions between them. + +## Phases + +1. **Ingest** (`/ingest`) — `ingest.md` + Frame the problem, identify user groups, and survey the competitive + landscape. Produces the discovery artifact. + +2. **Research** (`/research`) — `research.md` + Conduct user research — interviews, surveys, analytics, desk research. + Synthesize findings into insights and design recommendations. Conditional: + recommended when user needs are unclear or unvalidated; skippable if the + researcher already has validated research data. + +3. **Prototype** (`/prototype`) — `prototype.md` + Generate design prototypes informed by discovery and research findings. + Iterative — loops with `/evaluate`. + +4. **Evaluate** (`/evaluate`) — `evaluate.md` + Run heuristic evaluation and usability assessment against prototypes. + Iterative — loops back to `/prototype` or advances to `/handoff`. + +5. **Handoff** (`/handoff`) — `handoff.md` + Synthesize all prior artifacts into an implementation-ready spec with + component mapping, interaction specs, data annotations, persona-specific + views, and acceptance criteria. + +6. **Revise** (`/revise`) — `revise.md` + Incorporate stakeholder feedback into the handoff spec. Repeatable. + +6. **Publish** (`/publish`) — `publish.md` + Push the handoff spec as a PR to the docs repo for external review. + +7. **Respond** (`/respond`) — `respond.md` + Fetch and address PR reviewer comments on the published handoff spec. + +## Workspace + +All work happens in the **source repo** — the researcher needs codebase +context to make informed design decisions. Planning artifacts live in +`.artifacts/ux-design/{issue-key}/` (gitignored). + +### Artifact directory + +All working artifacts are stored in `.artifacts/ux-design/{issue-key}/` +within the source repo: + +| Artifact | File | Written by | +|----------|------|------------| +| Discovery brief | `01-discovery.md` | `/ingest` | +| Research findings | `02-research.md` | `/research` | +| Prototype files | `03-prototype/` | `/prototype` | +| Prototype notes | `03-prototype/prototype-notes.md` | `/prototype` | +| Evaluation report | `04-evaluation.md` | `/evaluate` | +| Implementation handoff | `05-handoff.md` | `/handoff` | +| PR description | `06-pr-description.md` | `/publish` | +| Publish metadata | `publish-metadata.json` | `/publish` | + +## How to Execute a Phase + +1. **Announce** the phase to the user: *"Starting /prototype."* +2. **Locate** the skill file — read and follow + `../../_shared/recipes/phase-override-resolution.md` with + WORKFLOW=`ux-design`, PHASE_FILE=`{phase}.md`. +3. **Read** the resolved skill file +4. **Execute** the skill's steps — the user should see your progress +5. When the skill is done, it will tell you to report findings and + re-read this controller. Do that — then use "Recommending Next Steps" + below to offer options. +6. Present the skill's results and your recommendations to the user +7. **Stop and wait** for the user to tell you what to do next. + +## Recommending Next Steps + +After each phase completes, present the user with **options** — not just one +next step. Use the typical flow as a baseline, but adapt to what actually +happened. + +### Typical Flow + +```text +ingest → [research] → prototype → evaluate → (iterate? → prototype) or → handoff → revise → publish → respond +``` + +Research is in brackets because it is conditional — not every feature needs +a dedicated research phase. Skip to `/prototype` if the researcher already +has validated data or well-understood user needs. + +### What to Recommend + +**Continuing forward:** + +- `/ingest` completed → recommend `/research` if user needs are unclear or + unvalidated; recommend `/prototype` directly if the researcher has + sufficient research data +- `/research` completed → recommend `/prototype` to explore design directions +- `/prototype` completed → recommend `/evaluate` (always — never skip evaluation) +- `/evaluate` completed (no critical issues) → recommend `/handoff` +- `/evaluate` completed (critical issues) → recommend `/prototype` to iterate +- `/handoff` completed → recommend `/revise` if the researcher wants + stakeholder feedback, or `/publish` to push the spec to the docs repo +- `/revise` completed → recommend `/publish` (or another `/revise` round) +- `/publish` completed → recommend sharing the PR with reviewers, then + `/respond` when comments arrive +- `/respond` completed → recommend another `/respond` round if new comments + arrive, or the workflow is done + +**When to recommend `/research`:** + +After `/ingest` completes, recommend `/research` when: +- The discovery brief surfaces significant unknowns about user needs +- The researcher doesn't have existing interviews, surveys, or analytics +- Competing design directions exist and research would break the tie +- The strategic decisions in the discovery brief require user data to resolve + +When the researcher already has validated research data or well-understood +user needs, recommend `/prototype` directly. + +**Iteration tracking:** + +- Track the number of prototype→evaluate cycles +- After 3 cycles, explicitly ask: "We've iterated 3 times. Ready for handoff, or continue refining?" +- The researcher decides — no hard cap + +**Looping back:** + +- `/research` reveals the problem framing is wrong → suggest revisiting `/ingest` +- `/prototype` reveals research gaps → suggest additional `/research` work +- `/evaluate` reveals fundamental design problems → suggest `/prototype` with specific changes +- `/handoff` reveals missing interaction specs → loop back to refine the prototype + +**Skipping:** + +- `/research` is always skippable — go directly to `/prototype` if the + researcher has sufficient domain knowledge or existing research data +- If the researcher already has a validated design, they may start at `/handoff` +- Phase entry requirements are listed below + +### Phase Entry + +Researchers can enter at any phase if they bring the prerequisite artifact: + +| Phase | Requires | +|-------|----------| +| `/ingest` | Jira issue key or feature description | +| `/research` | `01-discovery.md` (or equivalent problem framing) | +| `/prototype` | `01-discovery.md` + `02-research.md` (or equivalent; research skippable) | +| `/evaluate` | `03-prototype/` (prototype to evaluate) | +| `/handoff` | `04-evaluation.md` (or researcher confirms design is ready) | +| `/revise` | `05-handoff.md` | +| `/publish` | `05-handoff.md` | +| `/respond` | `publish-metadata.json` (PR must exist) | + +If a prerequisite artifact is missing, tell the researcher which phase +produces it and offer to run that phase first. + +### How to Present Options + +Lead with your top recommendation, then list alternatives briefly: + +```text +Recommended next step: /prototype — generate design prototypes based on +the approved research findings. + +Other options: +- /handoff — if you already have a validated design and want to skip prototyping +``` + +## Starting the Workflow + +Before dispatching any phase, check if the project has its own `AGENTS.md` +or `CLAUDE.md`. If so, read it — it may contain project-specific conventions +or design system guidance that affects how the workflow operates. + +When the user provides a Jira issue key or URL: +1. Execute the **ingest** phase +2. After ingestion, present results and wait + +If the user invokes a specific command (e.g., `/evaluate`), execute that +phase directly — don't force them through earlier phases. + +## Error Handling + +If any phase fails (Jira MCP errors, skill unavailability, file errors): + +1. **Stop immediately.** Do not advance to the next phase. +2. **Report the error** to the user with the specific error message. +3. **Offer options:** retry the failed step, skip the phase (if optional), + or escalate. + +Do not fabricate results when a tool call fails. Do not silently continue +past errors. Recovery must not advance to a later phase — report the error, +re-read this controller, and wait for user direction. + +## Context Management + +When the AI detects that its own output quality is degrading (e.g., it +misses details, repeats itself, or loses track of earlier decisions), +consider spawning the next phase as a subagent with a fresh context window. +This is self-monitoring by the AI, not something a human operator watches. +Load the subagent with the skill file for the phase being executed, the +relevant artifact files from `.artifacts/ux-design/{issue-key}/`, and the +project's `AGENTS.md`/`CLAUDE.md`. + +This is a recommendation, not a requirement — not all AI runtimes support +subagent spawning. + +## Rules + +- **Never auto-advance.** Always wait for the researcher between phases. +- **Recommendations come from this file, not from skills.** Skills report + findings; this controller decides what to recommend next. +- **Evaluation before handoff.** Never recommend `/handoff` unless + `/evaluate` has been run or the researcher explicitly skips it. +- **Skills degrade gracefully.** If a marketplace skill is unavailable, the + phase falls back to manual steps — the workflow still functions. +- **Research data is the researcher's.** The AI organizes and synthesizes + but does not fabricate or extrapolate beyond what the data supports. diff --git a/ux-design/skills/evaluate.md b/ux-design/skills/evaluate.md new file mode 100644 index 00000000..8d875678 --- /dev/null +++ b/ux-design/skills/evaluate.md @@ -0,0 +1,220 @@ +--- +name: evaluate +description: Heuristic evaluation and usability assessment of prototypes. +--- + +# Evaluate — Heuristic Evaluation + +Run systematic heuristic evaluation against the prototype to identify +usability issues before real user testing. AI-driven evaluation catches +systematic issues; only humans catch context-dependent problems. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/03-prototype/prototype-notes.md` +for design decisions and open questions. If `prototype-notes.md` doesn't +exist, tell the researcher that `/prototype` should run first and stop. + +Also read `.artifacts/ux-design/{issue-key}/01-discovery.md` for user group +context and problem framing. + +## Process + +### Step 1: Choose Evaluation Depth (Interactive) + +Ask the researcher what depth of evaluation is appropriate: + +| Depth | What it covers | When to use | +|-------|---------------|-------------| +| **Quick** | Rubric scoring only (Completeness, Usability, Feasibility — 0-2 each, max 6, pass >= 5 with no zeros) | Early iterations, rapid feedback | +| **Standard** | Rubric + simulated usability testing with personas (primary, power, infrequent user) + 4-8 task scenarios + severity-ranked issues | Most evaluations | +| **Full** | Standard + desirability study (word association, emotional response mapping, desirability score 1-10) | Final evaluation before handoff | + +Default to **Standard** unless the researcher specifies otherwise. + +If a selected depth's tools are unavailable, note "Tool unavailable — depth +downgraded to Standard" and confirm with the researcher before proceeding. + +### Step 2: Heuristic Evaluation + +Run `/uxd-workshop:uxd-research-heuristic-eval` against the prototype. +This is the primary evaluation tool — tested with an eval suite. + +This skill uses three independent AI-simulated evaluators: +- **Evaluator A:** Visual inspection +- **Evaluator B:** Task flow analysis +- **Evaluator C:** Edge cases and accessibility + +Findings are reconciled across evaluators and tagged by agreement level +(Unanimous, Majority, Single). Evaluators report **violations only** — +they do not assign severity or make design recommendations. The researcher +assigns severity during review. + +**Framework selection:** The skill will ask which heuristic framework to +use — do not default silently. Available frameworks: +- Nielsen's 10 Usability Heuristics +- Shneiderman's 8 Golden Rules +- ISO 9241-110 Interaction Principles +- Gerhardt-Powals' Cognitive Engineering Principles + +If this skill is not available, perform a manual heuristic inspection +using Nielsen's 10 as the default framework. + +### Step 3: Design Heuristics Scoring (Optional) + +If available, run `/uxd-workshop:uxd-evaluate-design-heuristics` for +structured scoring across dimensions: + +- Accessibility compliance +- Visual hierarchy and scannability +- Content and microcopy clarity +- State coverage (empty, loading, error, populated) +- Goal alignment + +Returns a Pass/Fail verdict with per-dimension scores (1-5), a critical +issues list, and an optional full report. + +If this skill is not available, skip this step. + +### Step 4: Simulated Usability Assessment + +If the chosen depth is **Standard** or **Full**, run +`/uxd-workshop:uxd-prototype-evaluate` at the matching depth: + +- **Standard:** Rubric scoring + simulated usability testing with personas + and task scenarios, severity-ranked issues (S1 critical through S4 + enhancement) +- **Full:** Standard + desirability study + +If this skill is not available, simulate usability scenarios manually: +define 3 personas (primary, power, infrequent user), 4-6 task scenarios, +and walk through each against the prototype. + +### Step 5: Cross-Reference with Research + +Compare evaluation findings against research data: + +- Do evaluation findings align with user needs from research? +- Are there usability issues that conflict with prioritized user needs? +- Do competitive patterns from discovery address any identified issues? + +### Step 6: Reconcile and Prioritize + +Combine findings from all evaluation methods and rank by severity: + +| Severity | Definition | +|----------|-----------| +| Critical | Prevents users from completing the primary task | +| Major | Causes significant confusion or extra effort | +| Minor | Noticeable friction but doesn't block task completion | +| Cosmetic | Aesthetic issue, no functional impact | + +Note the agreement level for each finding (how many evaluation methods +flagged it). Unanimous findings across methods carry highest confidence. + +### Step 7: Researcher Review (Required) + +**This is a hard gate — do not skip.** + +Present all candidate violations to the researcher. The researcher: +- Confirms or dismisses each finding +- Assigns final severity (AI-suggested severity is a starting point) +- Adds context the AI evaluation may have missed +- Decides which findings to address vs. accept + +The AI identifies violations; the researcher makes judgment calls. + +## Output + +`.artifacts/ux-design/{issue-key}/04-evaluation.md` + +```markdown +# Evaluation Report — {issue-key} + +**Date:** {date} +**Prototype iteration:** {N} +**Depth:** {Quick / Standard / Full} +**Framework:** {which heuristic framework was used} +**Methods:** {heuristic eval, design scoring, simulated usability, desirability} + +## Summary + +**Total issues:** {count} +**Critical:** {count} | **Major:** {count} | **Minor:** {count} | **Cosmetic:** {count} + +## Heuristic Evaluation Findings + +### Critical + +#### {Finding title} +- **Heuristic:** {which heuristic violated} +- **Agreement:** {Unanimous / Majority / Single} +- **Description:** {what the issue is} +- **Impact:** {how it affects users, traced to user group from research} +- **Recommendation:** {specific remediation} +- **Component:** {which part of the prototype} + +### Major +... + +### Minor +... + +### Cosmetic +... + +## Design Heuristics Scores + +| Dimension | Score (1-5) | Notes | +|-----------|------------|-------| +| Accessibility | {score} | {notes} | +| Visual hierarchy | {score} | {notes} | +| Content clarity | {score} | {notes} | +| State coverage | {score} | {notes} | +| Goal alignment | {score} | {notes} | + +**Verdict:** {Pass / Fail} + +## Usability Testing Results + +**Personas tested:** {list} +**Task scenarios:** {count} + +| Task | Primary User | Power User | Infrequent User | +|------|-------------|-----------|-----------------| +| {task} | {result} | {result} | {result} | + +## Accessibility Findings + +{Specific a11y issues: color contrast, keyboard navigation, screen reader + support, ARIA usage} + +## Readiness Assessment + +**Ready for handoff:** {Yes / No — needs iteration} +**Confidence:** {HIGH / MEDIUM / LOW} +**Rationale:** {why} + +## Iteration Recommendations + +{If not ready: specific changes for the next prototype iteration} +{If ready: any minor improvements to note in handoff} +``` + +Sections for unused methods (e.g., Design Heuristics Scores when that +skill was unavailable) should be omitted entirely. + +## When This Phase Is Done + +Present the evaluation to the researcher: +"Evaluation complete. {N} issues found — {critical} critical, {major} major. +{Readiness assessment}. Want to iterate on the prototype, or move to handoff?" + +**If iterating:** The researcher returns to `/prototype` to address findings. +Track the iteration count. After 3 cycles, prompt: "We've iterated 3 times. +Ready for handoff, or continue refining?" The researcher decides. + +**If ready for handoff:** Proceed to `/handoff`. + +Wait for the researcher's decision. Then **re-read the controller** +(`controller.md`) for next-step guidance. diff --git a/ux-design/skills/handoff.md b/ux-design/skills/handoff.md new file mode 100644 index 00000000..8c2cae94 --- /dev/null +++ b/ux-design/skills/handoff.md @@ -0,0 +1,236 @@ +--- +name: handoff +description: Synthesize research, prototype, and evaluation into an implementation-ready handoff spec. +--- + +# Handoff — Implementation Spec + +Synthesize all prior artifacts into a spec that a developer can implement +from. This is the contract between the ux-design workflow and `ui-design`. + +## Prerequisites + +Verify these artifacts exist before generating: +- `.artifacts/ux-design/{issue-key}/01-discovery.md` — problem context +- `.artifacts/ux-design/{issue-key}/03-prototype/` — design prototype +- `.artifacts/ux-design/{issue-key}/04-evaluation.md` — evaluation results + +If any are missing, stop and ask whether to run the owning phase or proceed +with an explicit partial-handoff caveat in the output. + +Read all available artifacts before proceeding. + +## Process + +### Step 1: Component Mapping + +Map each UI element in the validated prototype to specific design system +components: + +- If the project uses PatternFly, map to PatternFly components +- Reference the component's documented API/props +- Note any customization or composition required + +### Step 2: Interaction Specification + +Document every user interaction: + +- What happens on click, hover, focus, blur +- Form validation behavior (when, how, error messages) +- Loading states and transitions +- Navigation flow between views +- Keyboard interaction and shortcuts + +### Step 3: State Enumeration + +List every state the UI can be in: + +- **Empty** — no data yet, first-time experience +- **Loading** — data being fetched +- **Populated** — normal use with data +- **Error** — something went wrong (inline, toast, page-level) +- **Partial** — some data loaded, some failed +- **Responsive** — behavior at each breakpoint + +### Step 4: Data Annotations + +For each UI element that displays data, annotate what data it needs: + +- What information does this element display? +- Where does that data come from conceptually (not a specific API field — + that is `ui-design`'s job) +- Flag any data that may not exist in the backend — elements the UI + needs that the API may not currently support + +This gives `ui-design` the information it needs to map UI elements to API +endpoints and identify gaps. + +### Step 5: Persona-Specific Views + +Check `02-research.md` for persona notes. If multiple user groups interact +differently with the feature: + +- Identify which components or flows are shared vs. persona-specific +- Document persona-specific states, actions, or views +- Note permission-gated interactions (actions available to admins but + not viewers, etc.) + +If all user groups interact identically, note that explicitly rather than +omitting this section. + +### Step 6: Acceptance Criteria + +Write testable acceptance criteria derived from research findings: + +- Each criterion traces to a user need from research +- Each criterion is verifiable (pass/fail, not subjective) +- Include accessibility criteria from evaluation findings +- Cover persona-specific acceptance criteria where user groups differ + +### Step 7: Research Context Summary + +Summarize the key research decisions so developers understand *why*, +not just *what*: + +- Why this pattern over alternatives +- Which user needs drove each major decision +- What tradeoffs were made and why + +### Step 8: UXD Enhancement (optional) + +If `/uxd-workshop:uxd-design-handoff` is available, run it with the +handoff artifact (`05-handoff.md`) as input. Compare its output with the +spec above and strengthen the artifact with any additions: +- Missing state enumerations +- Acceptance criteria gaps +- Component mapping refinements + +If the skill is not available, skip this step. + +## Output + +`.artifacts/ux-design/{issue-key}/05-handoff.md` + +```markdown +# Implementation Handoff — {issue-key} + +**Date:** {date} +**Research cycle:** {number of prototype-evaluate iterations} + +## Summary + +{One paragraph: what the feature is, who it's for, and the core UX rationale} + +## User Stories + +{Derived from research insights — what users need and why} + +- As a {user group}, I need to {action} so that {outcome}. +- ... + +## Component Mapping + +| UI Element | Component | Props/Config | Notes | +|------------|-----------|-------------|-------| +| {element} | {component name} | {key props} | {customization needed} | + +## Page Layout + +{Description of the page structure — sections, regions, responsive behavior. + Reference prototype files for visual context.} + +## Interaction Specs + +### {Interaction area} +| Trigger | Action | Result | +|---------|--------|--------| +| {user action} | {system behavior} | {outcome} | + +### Form Behavior +| Field | Validation | Error Message | +|-------|-----------|---------------| +| {field} | {rule} | {message} | + +## States + +| State | What to show | Behavior | +|-------|-------------|----------| +| Empty | {description} | {interactions available} | +| Loading | {description} | {skeleton, spinner, etc.} | +| Error | {description} | {recovery actions} | +| Populated | {description} | {standard interactions} | + +## Responsive Behavior + +| Breakpoint | Layout Changes | +|-----------|---------------| +| Desktop (>1200px) | {behavior} | +| Tablet (768-1200px) | {behavior} | +| Mobile (<768px) | {behavior} | + +## Data Annotations + +{For each UI element that displays data, describe what information it + shows and where that data conceptually comes from. Flag anything the + UI needs that may not exist in the backend.} + +| UI Element | Data Needed | Notes / Gaps | +|------------|-------------|--------------| +| {element} | {what it displays} | {flag if backend support is uncertain} | + +## Persona-Specific Views + +{If multiple user groups interact differently with this feature, document + those differences here. If all groups interact identically, state that.} + +| User Group | Distinct Views or Actions | Permission Notes | +|------------|--------------------------|-----------------| +| {group} | {what's different} | {what's gated} | + +## Accessibility Requirements + +{From evaluation findings — specific a11y requirements} + +- {requirement with WCAG reference} +- ... + +## Acceptance Criteria + +| # | Criterion | Personas | Traces to | +|---|-----------|----------|-----------| +| AC1 | {testable criterion} | {all / specific group} | {Insight #N / User Need #N} | +| AC2 | {testable criterion} | {all / specific group} | {Insight #N / User Need #N} | + +## Research Context + +{Why these decisions were made — link to prior artifacts for full detail} + +- **Discovery:** `01-discovery.md` +- **Research:** `02-research.md` +- **Prototype:** `03-prototype/` +- **Evaluation:** `04-evaluation.md` + +### Key Design Decisions + +| Decision | Rationale | Alternative Considered | +|----------|-----------|----------------------| +| {what} | {why, traced to research} | {what was rejected and why} | +``` + +## When This Phase Is Done + +Present the handoff spec to the researcher: +"Here's the implementation handoff. Does this capture everything a developer +needs to build this feature? Any interaction details, data requirements, +or edge cases missing?" + +Wait for confirmation. The researcher may: +- Request additions or corrections → update the spec +- Approve → the workflow is complete + +When approved, report: +- Summary of the research cycle (phases completed, iterations) +- The handoff artifact location +- Any open questions or risks for implementation + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/ingest.md b/ux-design/skills/ingest.md new file mode 100644 index 00000000..b945e779 --- /dev/null +++ b/ux-design/skills/ingest.md @@ -0,0 +1,121 @@ +--- +name: ingest +description: Problem framing, user group identification, and competitive landscape survey. +--- + +# Ingest — Discovery + +Frame the problem, identify who it affects, and survey how others have +solved it. This phase produces the foundation that all downstream work +builds on. + +## Process + +### Step 1: Gather Context + +Read the Jira issue, PRD, or feature description provided by the researcher. +Extract: + +- **Problem statement** — what problem does this feature solve? +- **User groups** — who experiences this problem? What are their goals? +- **Existing state** — what does the product do today? What's the gap? +- **Constraints** — technical, business, or timeline constraints mentioned + +If a Jira issue key was provided, fetch the issue details. If a PRD exists +at `.artifacts/prd/{issue-key}/03-prd.md`, read it for additional context. + +If any external operation fails (Jira fetch, PRD lookup): note what failed, +continue with available data, and never fabricate context to fill the gap. + +Explore the codebase to understand the current UI: +- What pages/views exist in the affected area? +- What components are used? +- What user flows currently exist? + +### Step 2: Competitive Landscape + +Search for how other products solve this problem: + +- Direct competitors (similar products in the same space) +- Adjacent products (different domain, similar UX pattern) +- Design system references (PatternFly, Material, Atlassian patterns) + +For each relevant example, note: +- What they do well +- What they do poorly +- Patterns worth considering or avoiding + +### Step 3: Frame Strategic Decisions + +Based on the problem and landscape, identify the design decisions that +need to be made to move this work forward: + +- What design decisions depend on understanding user needs? +- Which assumptions need validation before the team can commit to a direction? +- What usability risks could change the approach? + +### Step 4: UXD Discovery Enhancement (optional) + +If `/uxd-workshop:uxd-discovery` is available, run it with the same +input source. Compare its output with the results above and merge any +additional findings into the discovery artifact: +- User groups the manual phase missed +- Competitive examples the skill surfaced +- Strategic decisions worth adding + +If the skill is not available, skip this step. + +## Output + +`.artifacts/ux-design/{issue-key}/01-discovery.md` + +```markdown +# Discovery — {issue-key} + +**Date:** {date} + +## Problem Statement + +{1-2 paragraphs: what problem, for whom, why it matters} + +## User Groups + +| Group | Goals | Pain Points | +|-------|-------|-------------| +| {group} | {what they're trying to do} | {what's hard today} | + +## Current State + +{What the product does today in this area. Include relevant file paths + or component references from the codebase.} + +## Competitive Landscape + +### {Product/Pattern A} +- **Approach:** {how they solve it} +- **Strengths:** {what works} +- **Weaknesses:** {what doesn't} + +### {Product/Pattern B} +... + +## Strategic Decisions + +1. {Decision the team needs to make, framed as "We need to decide..."} +2. {Decision the team needs to make, framed as "We need to decide..."} +... + +## Constraints + +- {Technical, business, or timeline constraints} +``` + +## When This Phase Is Done + +Present the discovery brief to the researcher: +"Here's the problem framing, user groups, and competitive landscape. +Does this capture the right scope? Any user groups, competitors, or +strategic decisions missing?" + +Wait for confirmation. Then **re-read the controller** (`controller.md`) +for next-step guidance. diff --git a/ux-design/skills/prototype.md b/ux-design/skills/prototype.md new file mode 100644 index 00000000..02f88322 --- /dev/null +++ b/ux-design/skills/prototype.md @@ -0,0 +1,163 @@ +--- +name: prototype +description: Generate design prototypes informed by research findings for evaluation. +--- + +# Prototype — Design Exploration + +Generate design prototypes based on research findings so the researcher +can react, refine, and evaluate. A rough prototype that sparks conversation +is more valuable than a polished one that can't be changed. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for problem context, +user groups, and competitive landscape. If it doesn't exist, ask the +researcher if they have an equivalent problem framing (PRD, feature brief, +or description). If they do, use it as context. If not, tell the researcher +that `/ingest` should run first and stop. + +If this is a re-entry from `/evaluate`, read `04-evaluation.md` for the +issues to address in this iteration. + +## Process + +### Step 1: Gather Input (Interactive) + +Determine what input is available for prototyping: + +| Input Source | How to gather | +|-------------|--------------| +| **Jira RFE** | Fetch the issue, extract requirements and acceptance criteria | +| **Figma designs** | Run `/uxd-workshop:uxd-figma-read` to extract design context (pages, frames, tokens). If unavailable, ask the researcher to describe the relevant frames. | +| **Feature description** | Use the discovery brief and any research the researcher provides | +| **Existing prototype** | Read the current prototype for refinement (iteration from `/evaluate`) | + +Ask the researcher to confirm the input source and scope before generating. + +### Step 2: Extract User Stories + +From the input source, extract or derive user stories: + +- Map each discovery insight to one or more user stories +- Include acceptance criteria derived from discovery and any research provided +- Prioritize stories by user need priority from `01-discovery.md` + +Save to `.artifacts/ux-design/{issue-key}/03-prototype/user-stories.json`. + +### Step 3: Design Direction (Interactive) + +Based on the research recommendations and user stories, propose 1-2 +design directions: + +For each direction: +- Which user needs does it prioritize? +- What's the core interaction pattern? +- What tradeoffs does it make? +- How does it compare to competitive approaches from discovery? + +Present directions to the researcher. Wait for them to choose or suggest +an alternative before generating. + +### Step 4: Generate Prototype + +Generate a prototype of the chosen direction. + +**If `/uxd-workshop:uxd-prototype-create` is available:** +Run it with the chosen input source. The skill supports two modes: +- **Auto mode:** Makes design decisions based on research findings and + design system patterns +- **Interactive mode:** Presents design decision pages for researcher + approval at each decision point + +Ask the researcher which mode to use. Default to interactive for first +iterations, auto for refinements. + +**If the skill is not available:** +Generate the prototype manually: +- If the project uses a design system (e.g., PatternFly), use documented + components +- Create standalone HTML or integrate into the existing codebase based on + the researcher's preference + +The prototype should cover: +- Primary user flow (happy path) +- Key interaction states (empty, loading, error, populated) +- The most critical user need from research + +Don't try to cover everything — prototype the riskiest or most uncertain +parts of the design first. + +Always write prototype files, metadata, and rationale to +`.artifacts/ux-design/{issue-key}/03-prototype/` before or alongside any +codebase integration. The `/evaluate` phase depends on this directory. + +### Step 5: Document Design Rationale + +For each design decision in the prototype, trace it back to a research +finding: + +- "This uses a wizard pattern because research showed users need step-by-step + guidance (Insight #2)" +- "The empty state includes a quick-start guide because 3/5 participants + struggled with initial setup" + +## Output + +`.artifacts/ux-design/{issue-key}/03-prototype/` + +``` +03-prototype/ +├── prototype-notes.md # Design rationale and decisions +├── user-stories.json # Extracted user stories with acceptance criteria +├── rfe-snapshot.md # Requirements snapshot (if sourced from Jira) +├── metadata.json # Prototype metadata (mode, iteration, input source) +├── {prototype files} # Generated prototype (HTML, React, screenshots) +└── iteration-{N}.md # Notes from each iteration (if iterating) +``` + +`prototype-notes.md` structure: + +```markdown +# Prototype — {issue-key} + +**Date:** {date} +**Iteration:** {N} +**Design direction:** {chosen direction} +**Mode:** {auto / interactive} +**Input source:** {Jira RFE / Figma / feature description / refinement} + +## Design Decisions + +| Decision | Rationale | Research Reference | +|----------|-----------|-------------------| +| {what} | {why} | {Insight #N from research} | + +## User Stories Covered + +| Story | Acceptance Criteria | Status | +|-------|-------------------|--------| +| {story} | {criteria} | {covered / partial / deferred} | + +## Scope + +**Covered in this prototype:** +- {flow or interaction covered} + +**Not yet covered:** +- {flow or interaction deferred} + +## Open Questions for Evaluation + +- {What should the evaluator focus on?} +- {Where is the design most uncertain?} +``` + +## When This Phase Is Done + +Present the prototype to the researcher: +"Here's a prototype of {direction}. It covers {scope}. Review it — what +works, what doesn't, what's missing? We can iterate or move to evaluation." + +Wait for confirmation. Then **re-read the controller** (`controller.md`) +for next-step guidance. diff --git a/ux-design/skills/publish.md b/ux-design/skills/publish.md new file mode 100644 index 00000000..a7ccf00a --- /dev/null +++ b/ux-design/skills/publish.md @@ -0,0 +1,180 @@ +--- +name: publish +description: Push the handoff spec as a GitHub PR for external review. +--- + +# Publish — Post Handoff Spec + +Post the finalized handoff spec as a GitHub pull request so technical +reviewers and stakeholders can review it. + +## Critical Rules + +- **Confirm before pushing.** Verify the target repository, branch name, and PR details with the user. +- **Draft PR.** Always create as a draft — the user decides when to mark it ready for review. +- **No force-push.** No destructive git operations. +- **No direct commits to main.** Always use a feature branch. + +## Process + +### Step 1: Read the Handoff Spec + +Read `.artifacts/ux-design/{issue-key}/05-handoff.md`. + +If the file doesn't exist, tell the user that `/handoff` should be run first. + +### Step 2: Resolve Docs Repo + +Check for an existing docs repo configuration at `.artifacts/config.json`. + +**If the config exists**, read it and validate: +1. Verify the path exists on the local filesystem +2. Verify the directory is a git repository +3. Verify the remote URL matches the configured `docs_repo_remote` + +**If the config does not exist**, ask the user: +- **Docs repo local path:** Where is the planning docs repo checked out? +- **Docs repo remote:** Run `git -C "{docs_repo_path}" remote get-url origin` + and confirm the result with the user + +Validate the path and remote, then save the config. + +Derive `{owner}/{repo}` from the remote URL (e.g., +`git@github.com:org/repo.git` → `org/repo`). + +### Step 3: Pre-Flight Checks + +Verify the environment: + +```bash +gh auth status +``` + +```bash +git -C "{docs_repo_path}" remote -v +``` + +```bash +git -C "{docs_repo_path}" status --porcelain +``` + +If the output is not empty, stop and tell the researcher the docs repo has +uncommitted changes that must be resolved before publishing. Do not proceed +with a dirty working tree. + +Confirm with the user: +- **Base branch:** Which branch should the PR target? (usually `main`) +- **Release:** Which release is this for? +- **Feature:** A short, lowercase, hyphenated slug with the issue key appended +- **Branch name:** Propose `ux-design/{issue-key}` and let the user override + +The handoff spec file path in the docs repo: `{release}/{feature}/handoff.md`. + +### Step 4: Create Branch and Commit + +All git operations run against the **docs repo**. Use +`git -C "{docs_repo_path}"` for all commands. + +```bash +git -C "{docs_repo_path}" checkout -b {branch-name} {base-branch} +``` + +```bash +mkdir -p "{docs_repo_path}/{release}/{feature}" +``` + +```bash +cp ".artifacts/ux-design/{issue-key}/05-handoff.md" "{docs_repo_path}/{release}/{feature}/handoff.md" +``` + +Run Vale against the copied file before staging: + +```bash +vale "{docs_repo_path}/{release}/{feature}/handoff.md" +``` + +If Vale reports errors, fix them in the source artifact and re-copy. +If Vale is not installed, note the skip and continue. + +```bash +git -C "{docs_repo_path}" add "{release}/{feature}/handoff.md" +``` + +```bash +git -C "{docs_repo_path}" commit -m "Add UX design handoff for {issue-key}: {title}" +``` + +### Step 5: Prepare PR Description + +Prepare the PR description and save it to `.artifacts/ux-design/{issue-key}/06-pr-description.md` +(in the source repo's artifact directory): + +```markdown +## UX Design Handoff: {title} + +**Jira:** {issue-link} + +### Summary +{2-3 sentence summary of what this handoff spec covers} + +### Requesting Review On +- Component mapping accuracy +- State enumeration completeness +- Acceptance criteria clarity +- Interaction specs correctness + +### How to Review +- Comment inline on specific sections +- Flag any missing states or interaction edge cases +- Approve when the handoff spec is implementation-ready +``` + +### Step 6: Push and Create PR + +```bash +git -C "{docs_repo_path}" push -u origin {branch-name} +``` + +Create a draft PR: + +```bash +gh pr create --draft --repo {owner}/{repo} --base {base-branch} --head {branch-name} --title "{issue-key}: UX Design Handoff - {title}" --body-file .artifacts/ux-design/{issue-key}/06-pr-description.md +``` + +### Step 7: Save Publish Metadata + +Write `.artifacts/ux-design/{issue-key}/publish-metadata.json`: + +```json +{ + "release": "{release}", + "feature": "{feature}", + "handoff_file_path": "{release}/{feature}/handoff.md", + "pr_number": "{pr-number}", + "branch": "{branch-name}" +} +``` + +### Step 8: Report to User + +Present: +- PR URL +- Docs repo and branch name +- File location in the docs repo +- Next steps (share with reviewers, then use `/respond` when comments arrive) + +## Output + +- `.artifacts/ux-design/{issue-key}/06-pr-description.md` +- `.artifacts/ux-design/{issue-key}/publish-metadata.json` +- Handoff spec committed and pushed to feature branch in the docs repo +- Draft PR created against the docs repo + +## When This Phase Is Done + +Report your results: +- PR URL and branch name +- Docs repo and file location +- Suggested next steps + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/research.md b/ux-design/skills/research.md new file mode 100644 index 00000000..1b3d8525 --- /dev/null +++ b/ux-design/skills/research.md @@ -0,0 +1,164 @@ +--- +name: research +description: User research, data gathering, and synthesis into insights and design recommendations. +--- + +# Research — User Research + +Conduct and synthesize user research to understand what users actually need. +The researcher drives data collection (interviews, surveys, observations); +the AI assists with organization, pattern identification, and synthesis. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for the problem +framing and strategic decisions. If it doesn't exist, tell the researcher +that `/ingest` should run first and stop. + +## Process + +### Stage 1: Research Plan (Interactive) + +#### Step 1: Propose Methodology + +Based on the discovery brief's strategic decisions, propose a research plan: + +- **Methods** — which research methods fit each question? (interviews, + surveys, analytics review, support ticket analysis) +- **Participants** — who should be included? How many? +- **Data sources** — what existing data can the AI analyze directly? + (support tickets, analytics, existing survey results, forum posts) + +Present the plan to the researcher. Wait for confirmation before proceeding. +The researcher knows their constraints — adapt the plan to what's feasible. + +#### Step 2: AI-Accessible Research + +While the researcher conducts interviews or observations, the AI performs +desk research that doesn't require human participants: + +- Analyze support tickets or bug reports related to the problem area +- Review forum posts, community discussions, or feedback channels +- Search for published usability studies on similar products +- Synthesize existing internal research documents + +Cite all sources. Flag confidence levels (HIGH/MEDIUM/LOW). + +### Stage 2: Data Organization (Collaborative) + +#### Step 3: Intake Research Data + +As the researcher gathers data (interview notes, survey responses, +observation notes), help organize it: + +- Group findings by theme, not by participant +- Identify recurring patterns across data sources +- Flag contradictions or surprising findings +- Note frequency — how many participants mentioned each theme? + +**Privacy:** Anonymize all participant data. Use role-based labels +("User P1", "Admin P2") instead of names. + +#### Step 4: Identify Patterns + +Across all data sources (researcher-gathered and AI desk research): + +- What themes appear across multiple sources? +- What user needs are consistent vs. edge cases? +- Where do different user groups have conflicting needs? +- What workarounds are users employing today? + +### Stage 3: Synthesis (Interactive) + +#### Step 5: Generate Insights + +Transform patterns into actionable insight statements: + +**Format:** "{User group} needs {capability} because {reason}, but currently +{barrier}." + +Each insight should: +- Be grounded in multiple data points +- Point toward a design direction +- Be specific enough to act on + +#### Step 6: Design Recommendations + +Based on insights, propose design recommendations: + +- What should the solution prioritize? +- What user needs are critical vs. nice-to-have? +- What design constraints emerged from research? +- What risks should the prototype address first? + +## Output + +`.artifacts/ux-design/{issue-key}/02-research.md` + +```markdown +# Research Findings — {issue-key} + +**Date:** {date} +**Methods:** {list of methods used} +**Participants:** {count and roles, anonymized} + +## Research Questions & Answers + +### Q1: {strategic decision from discovery} +**Finding:** {what we learned} +**Evidence:** {data points, quotes, sources} +**Confidence:** {HIGH/MEDIUM/LOW} + +### Q2: {strategic decision from discovery} +... + +## Key Insights + +1. **{Insight title}** + {User group} needs {capability} because {reason}, but currently {barrier}. + _Evidence: {data points}_ + +2. **{Insight title}** + ... + +## User Needs (Prioritized) + +| Priority | Need | User Groups | Evidence Strength | +|----------|------|-------------|-------------------| +| Must-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | +| Should-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | +| Nice-to-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | + +## Persona Notes + +{Where user groups interact differently with the feature, document + persona-specific needs here. This feeds directly into the handoff's + persona-specific views.} + +| User Group | Distinct Needs | Distinct Behaviors | +|------------|---------------|-------------------| +| {group} | {what's different for them} | {how they use the feature differently} | + +## Design Recommendations + +1. {Recommendation with rationale traced to insights} +2. ... + +## Risks & Open Questions + +- {Risk or unresolved question with impact on design} + +## Sources + +- {Source with URL or description} +``` + +## When This Phase Is Done + +Present the synthesized findings to the researcher: +"Here are the research findings and design recommendations. Do these +insights accurately reflect what you learned? Anything to add or correct +before we move to prototyping?" + +Wait for confirmation. Then **re-read the controller** (`controller.md`) +for next-step guidance. diff --git a/ux-design/skills/respond.md b/ux-design/skills/respond.md new file mode 100644 index 00000000..2787f212 --- /dev/null +++ b/ux-design/skills/respond.md @@ -0,0 +1,130 @@ +--- +name: respond +description: Fetch and address reviewer comments on the published handoff spec PR. +--- + +# Respond — Address Review Comments + +Fetch reviewer comments from the GitHub PR, help the user understand and +respond to them, and apply any resulting handoff spec changes. + +## Critical Rules + +- **Never post comments without user approval.** Propose responses, then wait. +- **Separate content changes from clarifications.** Some comments need handoff spec edits; others just need a reply. +- **Preserve the review trail.** Don't delete or modify existing comments. +- **Allowed `gh` operations:** + - **Read:** `gh pr view`, `gh api` GET + - **Write:** `gh pr comment`, `gh api` POST to reply to review comments + - **Forbidden:** `gh pr close`, `gh pr merge`, `gh pr edit`, `gh pr ready` + +## Process + +### Step 1: Fetch PR Comments + +Read `.artifacts/config.json` to get the docs repo path and +`.artifacts/ux-design/{issue-key}/publish-metadata.json` to get the PR +number and `{branch-name}`. If either file doesn't exist, tell the user +that `/publish` should be run first. + +Determine `{owner}/{repo}` from the config's `docs_repo_remote`. + +```bash +gh pr view {pr-number} --repo {owner}/{repo} --json comments,reviews,url +``` + +```bash +gh api repos/{owner}/{repo}/pulls/{pr-number}/comments --paginate +``` + +If no comments are found, tell the user and suggest checking back later. + +### Step 2: Categorize Comments + +| Category | Action | +|----------|--------| +| **Clarification request** | Draft a reply explaining the rationale | +| **Design alternative** | Evaluate the suggestion, propose a response | +| **Factual correction** | Update the handoff spec and acknowledge | +| **Scope question** | Draft a reply; may need `/revise` | +| **New requirement** | Flag for user decision — update or defer | +| **Approval / positive** | Acknowledge | + +### Step 3: Propose Responses + +Present each comment with a proposed response: + +```markdown +## Review Comment Summary + +### Comment 1 — {reviewer} +> {quoted comment text} + +**Category:** {category} +**Proposed response:** {your suggested reply} +**Handoff change needed:** {Yes/No — description if yes} +``` + +Wait for the user to approve, modify, or reject each response. + +### Step 4: Apply Approved Changes + +Update `.artifacts/ux-design/{issue-key}/05-handoff.md` with approved changes. + +Update the docs repo copy: + +```bash +git -C "{docs_repo_path}" checkout {branch-name} +``` + +```bash +git -C "{docs_repo_path}" pull --ff-only +``` + +```bash +cp ".artifacts/ux-design/{issue-key}/05-handoff.md" "{docs_repo_path}/{handoff_file_path}" +``` + +Run Vale against the updated file before staging: + +```bash +vale "{docs_repo_path}/{handoff_file_path}" +``` + +If Vale reports errors, fix them in the source artifact and re-copy. +If Vale is not installed, note the skip and continue. + +```bash +git -C "{docs_repo_path}" add "{handoff_file_path}" +``` + +```bash +git -C "{docs_repo_path}" commit -m "UX design {issue-key}: address review feedback" +``` + +```bash +git -C "{docs_repo_path}" push +``` + +Post approved replies using `gh pr comment` or `gh api` for line-level replies. + +### Step 5: Report to User + +Summarize: +- How many comments were addressed +- How many handoff spec changes were made +- Whether any comments remain unresolved + +## Output + +- PR comments posted (with user approval) +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (updated if needed) + +## When This Phase Is Done + +Report your results: +- Comments addressed and responses posted +- Handoff spec changes made +- Outstanding items + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/revise.md b/ux-design/skills/revise.md new file mode 100644 index 00000000..ade5195d --- /dev/null +++ b/ux-design/skills/revise.md @@ -0,0 +1,78 @@ +--- +name: revise +description: Incorporate stakeholder feedback into the handoff spec. +--- + +# Revise — Update Handoff Spec + +Incorporate the user's feedback into the existing handoff spec while +maintaining consistency across all prior artifacts. This phase is +repeatable — the user may request multiple rounds of revision. + +## Critical Rules + +- **Change only what's requested.** Do not "improve" sections the user didn't mention. +- **Maintain consistency across artifacts.** If a handoff change contradicts research findings or evaluation results, flag it. +- **Show your changes.** After revising, summarize what changed so the user can verify. + +## Process + +### Step 1: Read Current Artifacts + +Read the handoff spec and prior artifacts: +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (the deliverable) +- `.artifacts/ux-design/{issue-key}/04-evaluation.md` (evaluation context) +- `.artifacts/ux-design/{issue-key}/01-discovery.md` (problem context) + +### Step 2: Understand the Feedback + +The user's feedback may target: +- Component mapping changes +- Interaction spec corrections +- State coverage gaps +- Acceptance criteria adjustments +- Research context clarifications + +Clarify with the user if the feedback is ambiguous before making changes. + +### Step 3: Apply Changes + +Edit the handoff spec: +- For specific edits: apply them directly +- For directional feedback: propose concrete changes and confirm before applying +- For new information: add it to the appropriate sections + +### Step 4: Consistency Check + +After applying changes, verify: +- Do acceptance criteria still trace to research findings? +- Does the component mapping still align with the prototype? +- Are interaction specs consistent with evaluation findings? +- Are there contradictions with locked research decisions? + +### Step 5: Present Changes + +Summarize what changed: + +```markdown +## Revision Summary + +### Handoff Changes +- {Section}: {what changed and why} + +### Consistency Updates +- {any cascading updates to maintain coherence} +``` + +## Output + +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (updated) + +## When This Phase Is Done + +Report your results: +- What was changed and why +- Any consistency updates made as a side effect +- Any remaining open questions + +Then **re-read the controller** (`controller.md`) for next-step guidance. From 7cc98a6a5e01f000d57d2da580993ae2afa3b4d1 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 21 Aug 2026 16:27:07 -0400 Subject: [PATCH 02/15] Refine ux-design workflow: bare-skill deps, refine loop, provenance Address code review of the ux-design workflow: - Drop the /uxd-workshop: plugin namespace everywhere in favor of bare skill names, matching what install.sh symlinks and the only form that resolves across Claude Code, Cursor, and Gemini. - Fix the prototype->evaluate refine loop: stage or synthesize reviews/summary.md so iteration works at Quick depth. - Make artifact mirroring explicit, mode-aware, and non-lossy; mirror rfe-snapshot.md/metadata.json/prototype-summary.yaml/workspace files; clean up skill scratch (.artifacts/{ID}/, pipeline-report.html) to honor artifact isolation. - Locate, read back, and clean up the stray design-handoff output. - Add an evaluation-input production step + fail-loud gate; require screenshots at Standard/Full depth for uxd-evaluate-design-heuristics. - Add an S1-S4 -> Critical/Major/Minor/Cosmetic crosswalk. - Wire the provenance contract for 05-handoff.md to match prd/design: per-workflow ORIGIN_PHASE (ux-design originates in handoff), capture on handoff/revise/respond, render footer on publish/respond. Add tests. - Add the ${CLAUDE_SKILL_DIR} shim (fail loud) for script-backed skills. Assisted-by: Claude claude-opus-4-8 (200K context) --- _shared/recipes/capture-provenance-event.md | 4 +- _shared/recipes/render-provenance-footer.md | 2 +- _shared/scripts/provenance.py | 47 +++- _shared/scripts/test_provenance.py | 22 ++ install.sh | 30 ++- ux-design/README.md | 40 ++- ux-design/guidelines.md | 64 +++-- ux-design/skills/controller.md | 18 +- ux-design/skills/evaluate.md | 272 +++++++++++++++++--- ux-design/skills/handoff.md | 265 +++++++++---------- ux-design/skills/ingest.md | 111 ++++---- ux-design/skills/prototype.md | 224 +++++++++++----- ux-design/skills/publish.md | 21 +- ux-design/skills/respond.md | 15 +- ux-design/skills/revise.md | 17 ++ 15 files changed, 786 insertions(+), 366 deletions(-) diff --git a/_shared/recipes/capture-provenance-event.md b/_shared/recipes/capture-provenance-event.md index 236a6e6f..bab6797e 100644 --- a/_shared/recipes/capture-provenance-event.md +++ b/_shared/recipes/capture-provenance-event.md @@ -11,9 +11,9 @@ phase mutates the planning document. See `../provenance-schema.md`. | Parameter | Required | Description | |-----------|----------|-------------| -| WORKFLOW | Yes | `prd` or `design` | +| WORKFLOW | Yes | `prd`, `design`, or `ux-design` | | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) | -| PHASE | Yes | `draft`, `revise`, or `respond` | +| PHASE | Yes | `draft`, `revise`, or `respond` (ux-design also uses `handoff`) | | AUTHORING_MODE | Yes | `skill` (default for phase skills) or `manual` | ## Procedure diff --git a/_shared/recipes/render-provenance-footer.md b/_shared/recipes/render-provenance-footer.md index de7154d7..271e6cef 100644 --- a/_shared/recipes/render-provenance-footer.md +++ b/_shared/recipes/render-provenance-footer.md @@ -11,7 +11,7 @@ Render the durable `## Provenance` footer into a docs-repo markdown file before | Parameter | Required | Description | |-----------|----------|-------------| -| WORKFLOW | Yes | `prd` or `design` | +| WORKFLOW | Yes | `prd`, `design`, or `ux-design` | | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) | | TARGET_FILE | Yes | Absolute path to the docs-repo file about to be committed | | ALLOW_MISSING | No | Set to `yes` only after the user explicitly declines provenance | diff --git a/_shared/scripts/provenance.py b/_shared/scripts/provenance.py index 0a292c85..eef745f3 100755 --- a/_shared/scripts/provenance.py +++ b/_shared/scripts/provenance.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Capture and render provenance for prd/design planning document workflows. +"""Capture and render provenance for prd/design/ux-design planning documents. Exit codes: 0: Success (capture or render completed) @@ -23,9 +23,22 @@ WORKFLOW_DOCS = { "prd": "03-prd.md", "design": "03-design.md", + "ux-design": "05-handoff.md", } -AUTHORING_PHASES = frozenset({"draft", "revise", "respond", "manual-edit"}) +# The phase that legitimately originates each workflow's document. prd/design +# originate from a template-checked /draft; ux-design assembles its handoff spec +# in /handoff (there is no template-from-origin step), so `handoff` is its +# origin. A first event other than this marks the phase history as untracked. +ORIGIN_PHASE = { + "prd": "draft", + "design": "draft", + "ux-design": "handoff", +} + +AUTHORING_PHASES = frozenset( + {"draft", "handoff", "revise", "respond", "manual-edit"} +) DRIFT_FIELDS = ( "workflow_version", @@ -56,10 +69,12 @@ COMMIT_ONLY_NOTE = ( "> Authoring phases not recorded this session (commit-time snapshot only)." ) -ORIGIN_UNTRACKED_NOTE = ( - "> This document's phase history does not include an initial /draft — " - "structure was not verified against the template from origin." -) +def origin_untracked_note(workflow: str | None = None) -> str: + origin = ORIGIN_PHASE.get(workflow, "draft") + return ( + f"> This document's phase history does not include an initial /{origin} — " + "structure was not verified against the template from origin." + ) def repo_root(start: Path) -> Path | None: @@ -260,12 +275,15 @@ def provenance_kind(events: list[dict[str, Any]]) -> str: return "session" -def origin_untracked(events: list[dict[str, Any]]) -> bool: +def origin_untracked( + events: list[dict[str, Any]], workflow: str | None = None +) -> bool: if not events: return False if provenance_kind(events) == "commit_only": return False - return events[0].get("phase") != "draft" + origin = ORIGIN_PHASE.get(workflow, "draft") + return events[0].get("phase") != origin def capture_event( @@ -352,6 +370,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]: last = events[-1] if events else {} drift = data.get("drift", {}) kind = provenance_kind(events) + workflow = data.get("workflow", "unknown") return { "schema_version": 1, "provenance_kind": kind, @@ -368,7 +387,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]: {event.get("authoring_mode", "skill") for event in events} ), "context_changed": drift.get("context_changed", False), - "origin_untracked": origin_untracked(events), + "origin_untracked": origin_untracked(events, workflow), } @@ -403,9 +422,9 @@ def build_footer(data: dict[str, Any]) -> str: if len(phases) > 1: lines.append(f"Phases: {', '.join(phases)}") - if origin_untracked(events): + if origin_untracked(events, workflow): lines.append("") - lines.append(ORIGIN_UNTRACKED_NOTE) + lines.append(origin_untracked_note(workflow)) lines.append("") lines.append(metrics_comment) @@ -491,7 +510,9 @@ def render_footer(workflow: str, issue: str, target: Path, *, allow_missing: boo def main() -> int: - parser = argparse.ArgumentParser(description="PRD/design provenance helper") + parser = argparse.ArgumentParser( + description="PRD/design/ux-design provenance helper" + ) sub = parser.add_subparsers(dest="command", required=True) capture = sub.add_parser("capture", help="Append a provenance event") @@ -500,7 +521,7 @@ def main() -> int: capture.add_argument( "--phase", required=True, - choices=["draft", "revise", "respond", "manual-edit", "commit"], + choices=["draft", "handoff", "revise", "respond", "manual-edit", "commit"], ) capture.add_argument( "--authoring-mode", diff --git a/_shared/scripts/test_provenance.py b/_shared/scripts/test_provenance.py index 7086d17f..b38ffb11 100644 --- a/_shared/scripts/test_provenance.py +++ b/_shared/scripts/test_provenance.py @@ -107,6 +107,28 @@ def test_origin_untracked_false_when_all_events_are_commit(self) -> None: self.assertEqual(provenance.provenance_kind(events), "commit_only") self.assertFalse(provenance.origin_untracked(events)) + def test_origin_untracked_false_for_ux_design_handoff_first(self) -> None: + # ux-design originates its document in /handoff (not /draft), so a + # handoff-first log is a tracked origin and must NOT be flagged. + events = [{"phase": "handoff"}, {"phase": "revise"}] + self.assertFalse(provenance.origin_untracked(events, "ux-design")) + + def test_origin_untracked_true_for_ux_design_revise_first(self) -> None: + # ux-design entered at /revise with no prior /handoff is untracked. + events = [{"phase": "revise"}] + self.assertTrue(provenance.origin_untracked(events, "ux-design")) + + def test_origin_untracked_true_for_prd_handoff_first(self) -> None: + # 'handoff' is not prd's origin phase, so a handoff-first prd log is + # still untracked -- the per-workflow origin must not leak across. + events = [{"phase": "handoff"}] + self.assertTrue(provenance.origin_untracked(events, "prd")) + + def test_origin_untracked_note_names_workflow_origin_phase(self) -> None: + self.assertIn("/handoff", provenance.origin_untracked_note("ux-design")) + self.assertIn("/draft", provenance.origin_untracked_note("prd")) + self.assertIn("/draft", provenance.origin_untracked_note()) + def test_build_metrics_payload_flags_origin_untracked(self) -> None: data = { "workflow": "prd", diff --git a/install.sh b/install.sh index 05709eb8..8538bef0 100755 --- a/install.sh +++ b/install.sh @@ -132,6 +132,7 @@ ensure_repo_linked() { } UXD_REPO="https://github.com/rh-uxd/ai-helpers.git" +UXD_SHA="ad44b9c92c89730da5191487d0ff82af09b41366" UXD_DIR="${HOME}/.uxd-ai-skills" UXD_PLUGINS=(uxd-workshop) @@ -148,10 +149,31 @@ install_uxd_skills() { "$has_ux_design" || return 0 if [[ ! -d "$UXD_DIR" ]]; then - echo " Cloning UXD AI Skills repo..." - git clone --depth 1 "$UXD_REPO" "$UXD_DIR" 2>/dev/null || { - echo " Warning: could not clone UXD AI Skills repo; ux-design optional skills unavailable" >&2 - return 0 + echo " Cloning UXD AI Skills repo (${UXD_SHA:0:7})..." + git clone "$UXD_REPO" "$UXD_DIR" 2>/dev/null || { + echo " Error: could not clone UXD AI Skills repo — ux-design workflow requires it" >&2 + echo " Check network access to github.com and re-run install." >&2 + return 1 + } + git -C "$UXD_DIR" checkout "$UXD_SHA" 2>/dev/null || { + echo " Error: could not check out UXD AI Skills commit ${UXD_SHA:0:7}" >&2 + return 1 + } + else + # Existing install: make sure it is on the pinned SHA. Fetch first in case + # the local clone predates the pinned commit; a fetch failure is non-fatal + # only when the commit is already present locally. + if ! git -C "$UXD_DIR" cat-file -e "${UXD_SHA}^{commit}" 2>/dev/null; then + echo " Fetching UXD AI Skills updates (${UXD_SHA:0:7})..." + git -C "$UXD_DIR" fetch origin 2>/dev/null || { + echo " Error: could not fetch UXD AI Skills commit ${UXD_SHA:0:7}" >&2 + echo " Check network access to github.com and re-run install." >&2 + return 1 + } + fi + git -C "$UXD_DIR" checkout "$UXD_SHA" 2>/dev/null || { + echo " Error: could not check out UXD AI Skills commit ${UXD_SHA:0:7}" >&2 + return 1 } fi diff --git a/ux-design/README.md b/ux-design/README.md index e38c76cb..e2c64ab6 100644 --- a/ux-design/README.md +++ b/ux-design/README.md @@ -28,7 +28,8 @@ already has validated data or well-understood user needs. | Tool | Required | Purpose | |------|----------|---------| | Jira access (MCP or CLI) | For `/ingest` | Fetch issue details for problem framing | -| UXD marketplace plugins | Optional | Enhances `/ingest`, `/prototype`, `/evaluate`, `/handoff` | +| UXD skills (`uxd-workshop`) | Required | Prototype generation, heuristic evaluation, discovery, handoff | +| `python3` on PATH | For `/evaluate` (Standard/Full) | `uxd-prototype-evaluate` helper scripts | ## Phases @@ -90,10 +91,13 @@ All artifacts are stored in `.artifacts/ux-design/{issue-key}/`. .artifacts/ux-design/EDM-1234/ 01-discovery.md (problem framing, user groups, landscape) 02-research.md (research findings, insights, recommendations) - 03-prototype/ (prototype files, design rationale) + 03-prototype/ (mirrored skill output + design rationale) prototype-notes.md (design decisions, user stories covered) + prototype/ (generated prototype files, from the skill) 04-evaluation.md (heuristic eval report, readiness assessment) + 04-eval-raw/ (raw skill reports, mirrored from the eval skills) 05-handoff.md (implementation spec, component mapping, AC) + provenance.json (authoring provenance log) ``` ## Handoff Contract @@ -111,21 +115,43 @@ It contains: ## UXD Marketplace Skills -This workflow optionally uses skills from the +This workflow requires skills from the [UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). -All phases function without them — the skills enhance output quality -but are not required. +These skills are a hard dependency — phases that use them will stop and prompt +you to run `./install.sh` if they are missing. + +`install.sh` installs them **AI-agnostically**: it clones the `rh-uxd/ai-helpers` +repo (pinned to a specific commit) and symlinks each skill into the skills +directory for your AI tool (Claude Code, Cursor, or Gemini). The skills are +installed and invoked by **bare name** (`uxd-discovery`, `uxd-prototype-create`, +…), *not* through Claude Code's `/uxd-workshop:` plugin-marketplace +namespace — the bare-name form is the one that resolves across all three tools. | Skill | Plugin | Used by | |-------|--------|---------| | `uxd-discovery` | `uxd-workshop` | `/ingest` | | `uxd-prototype-create` | `uxd-workshop` | `/prototype` | -| `uxd-figma-read` | `uxd-workshop` | `/prototype` | | `uxd-research-heuristic-eval` | `uxd-workshop` | `/evaluate` | | `uxd-evaluate-design-heuristics` | `uxd-workshop` | `/evaluate` | -| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` (Standard/Full depth) | | `uxd-design-handoff` | `uxd-workshop` | `/handoff` | +`uxd-prototype-create` reads Figma links directly, so the workflow does not +invoke `uxd-figma-read` separately (`install.sh` still symlinks it if you want to +use it standalone). + +**Runtime note:** the script-backed skills (`uxd-prototype-create` and +`uxd-prototype-evaluate`) run Python helpers via the `${CLAUDE_SKILL_DIR}` +environment variable, which only Claude Code sets. Under Cursor or Gemini it is +unset, so `/prototype` and `/evaluate` resolve the scripts from the deterministic +install path (`${HOME}/.uxd-ai-skills/plugins/uxd-workshop/skills/`) and +substitute it inline. If **neither** the variable nor that path resolves to a +real `scripts/` directory (or a helper is missing), the phase stops and reports +the error rather than silently downgrading a Standard/Full evaluation to Quick. +This `${CLAUDE_SKILL_DIR}` workaround is the one runtime-specific wrinkle, and it +would be removed by an upstream change to how the skills resolve their scripts. +The remaining skills use no runtime-specific mechanisms. + ## Directory Structure ```text diff --git a/ux-design/guidelines.md b/ux-design/guidelines.md index 328ebce7..cd8ac41b 100644 --- a/ux-design/guidelines.md +++ b/ux-design/guidelines.md @@ -2,50 +2,72 @@ ## Principles -- The researcher drives the process. The AI assists with synthesis, generation, - and evaluation — it does not make research decisions autonomously. -- Every design decision must trace to research findings. Do not invent user - needs or fabricate evidence. +- The handoff spec represents the **team's** agreed UX approach, not the AI's + interpretation. Always confirm before finalizing content. +- Trace every design decision back to a research finding or user direction. + Do not invent user needs or fabricate evidence. - **Evidence over assumption.** When research data is unavailable, say so - explicitly. "We don't have data on this" is valuable. + explicitly. "We don't have data on this" is valuable — silence is not. +- **Precision over verbosity.** A concise, well-structured handoff gets better + reviews. Cover everything that matters; don't pad it. - Preserve the researcher's terminology and domain language. Do not rewrite their findings into generic UX jargon. - Prototypes are conversation starters, not final designs. A rough prototype the researcher can react to is more valuable than a polished one they can't. - Heuristic evaluation supplements — never replaces — real user testing. AI-driven evaluation catches systematic issues; only humans catch context- - dependent usability problems. Heuristic and simulated evaluation inform - design iteration but do not constitute usability validation. The handoff - spec must note evaluation method and flag when real user testing has not - been conducted. + dependent usability problems. The handoff spec must note the evaluation + method and flag when real user testing has not been conducted. +- **Research is conditional.** Not every feature needs a dedicated research + phase. `/research` is recommended when user needs are unclear or unvalidated. + Skip to `/prototype` if the researcher already has validated data. ## Hard Limits - No auto-advancing between phases. Always wait for the researcher. - No fabricated research findings. Every insight must trace to data the researcher provided or desk research the AI performed with citations. -- No storing PII in artifacts. User interview data should be anonymized - before inclusion. -- No publishing prototypes or artifacts without explicit researcher approval. +- No storing PII in artifacts. User interview data must be anonymized before + inclusion. Use role-based labels ("User P1", "Admin P2"), not names. +- No publishing artifacts without explicit researcher approval. - No skipping the human gate between phases. Present findings, get confirmation. +- No committing to `main` directly. Use feature branches for `/publish`. +- **No personal names in generated content.** Replace references to individuals + from Jira tickets, interview notes, or other source material with role-based + descriptions ("the fleet admin reported…", "a participant noted…"). Author + metadata fields are exempt — they identify the document author, not + referenced individuals. +- **No scope reduction.** Never silently defer design decisions to "v2" or + mark states as "future enhancement" to reduce scope. If scope won't fit + a single research cycle, propose a split — don't quietly drop it. ## Safety - Show your work before finalizing. After each phase, present artifacts for - review — do not assume they're ready. + review — do not assume they are ready. - Flag assumptions explicitly. If research data doesn't cover something and - you filled it in, mark it as an assumption. + you filled it in, mark it clearly as an assumption. - Indicate confidence levels on recommendations. Distinguish between findings - backed by multiple data sources and single-source observations. + backed by multiple data sources (HIGH) and single-source observations (LOW). +- Before `/publish`, confirm the target repository, branch, and PR details + with the researcher. ## Quality -- Artifacts should be structured for both human reading and machine - consumption. Use consistent markdown with headings. -- Handoff artifacts must be detailed enough for a developer to implement - without additional design consultation. +- Artifacts must be structured for both human reading and machine consumption. + Use consistent markdown headings and table formats — downstream workflows + (ui-design, ui-implement) parse these artifacts programmatically. +- The handoff spec must be detailed enough for a developer to implement without + additional design consultation. If a developer would need to ask a question, + the answer belongs in the spec. - Heuristic evaluation findings must include severity ratings and specific - remediation guidance. + remediation guidance — not just observations. +- Acceptance criteria must be **behavioral outcomes** (what the system does, + testable from outside), not activities or implementation details. +- The Data Annotations and Persona-Specific Views sections of the handoff spec + are required, not optional. If all user groups interact identically, say so + explicitly. If no UI element has data uncertainty, say so explicitly. Do not + omit these sections. ## Escalation @@ -57,6 +79,7 @@ Stop and request human guidance when: - Heuristic evaluation reveals critical accessibility violations that may require architectural changes - The researcher's domain expertise is needed to interpret data +- Confidence in a design recommendation is low ## Working With the Project @@ -65,3 +88,4 @@ This workflow gets deployed into different projects. Respect the target project: - Read and follow the project's own `AGENTS.md` or `CLAUDE.md` files - Adopt the project's conventions for document formatting if they exist - Use the project's design system and component library for prototyping +- Use the configured docs repository for `/publish` operations diff --git a/ux-design/skills/controller.md b/ux-design/skills/controller.md index 902f9018..a62e6c4f 100644 --- a/ux-design/skills/controller.md +++ b/ux-design/skills/controller.md @@ -36,10 +36,10 @@ by executing phases and handling transitions between them. 6. **Revise** (`/revise`) — `revise.md` Incorporate stakeholder feedback into the handoff spec. Repeatable. -6. **Publish** (`/publish`) — `publish.md` +7. **Publish** (`/publish`) — `publish.md` Push the handoff spec as a PR to the docs repo for external review. -7. **Respond** (`/respond`) — `respond.md` +8. **Respond** (`/respond`) — `respond.md` Fetch and address PR reviewer comments on the published handoff spec. ## Workspace @@ -61,6 +61,7 @@ within the source repo: | Prototype notes | `03-prototype/prototype-notes.md` | `/prototype` | | Evaluation report | `04-evaluation.md` | `/evaluate` | | Implementation handoff | `05-handoff.md` | `/handoff` | +| Provenance log | `provenance.json` | `/handoff`, `/revise`, `/respond` | | PR description | `06-pr-description.md` | `/publish` | | Publish metadata | `publish-metadata.json` | `/publish` | @@ -153,7 +154,7 @@ Researchers can enter at any phase if they bring the prerequisite artifact: | `/ingest` | Jira issue key or feature description | | `/research` | `01-discovery.md` (or equivalent problem framing) | | `/prototype` | `01-discovery.md` + `02-research.md` (or equivalent; research skippable) | -| `/evaluate` | `03-prototype/` (prototype to evaluate) | +| `/evaluate` | `03-prototype/` (prototype to evaluate). Standard/Full depth also needs the skill `{ID}` recorded in `03-prototype/prototype-notes.md`, and the mirrored native layout under `03-prototype/` so `.artifacts/{ID}/` can be recreated | | `/handoff` | `04-evaluation.md` (or researcher confirms design is ready) | | `/revise` | `05-handoff.md` | | `/publish` | `05-handoff.md` | @@ -210,8 +211,10 @@ Load the subagent with the skill file for the phase being executed, the relevant artifact files from `.artifacts/ux-design/{issue-key}/`, and the project's `AGENTS.md`/`CLAUDE.md`. -This is a recommendation, not a requirement — not all AI runtimes support -subagent spawning. +This is a recommendation, not a requirement, and it applies to **Claude Code +only** — Cursor and Gemini do not support an AI self-directing subagent +spawning. Under those runtimes, manage context by keeping phases short and +relying on the artifact files to carry state between phases. ## Rules @@ -220,7 +223,8 @@ subagent spawning. findings; this controller decides what to recommend next. - **Evaluation before handoff.** Never recommend `/handoff` unless `/evaluate` has been run or the researcher explicitly skips it. -- **Skills degrade gracefully.** If a marketplace skill is unavailable, the - phase falls back to manual steps — the workflow still functions. +- **Skills are required.** The `uxd-workshop` skills are a hard dependency. + If a skill is unavailable, the phase stops and directs the researcher + to run `./install.sh`. - **Research data is the researcher's.** The AI organizes and synthesizes but does not fabricate or extrapolate beyond what the data supports. diff --git a/ux-design/skills/evaluate.md b/ux-design/skills/evaluate.md index 8d875678..d107a9bd 100644 --- a/ux-design/skills/evaluate.md +++ b/ux-design/skills/evaluate.md @@ -9,6 +9,12 @@ Run systematic heuristic evaluation against the prototype to identify usability issues before real user testing. AI-driven evaluation catches systematic issues; only humans catch context-dependent problems. +## Dependencies + +This phase requires the `uxd-workshop` skills. If any required skill is +not available, stop and tell the researcher to run `./install.sh` to set up +the uxd-workshop skills before proceeding. + ## Prerequisites Read `.artifacts/ux-design/{issue-key}/03-prototype/prototype-notes.md` @@ -18,52 +24,115 @@ exist, tell the researcher that `/prototype` should run first and stop. Also read `.artifacts/ux-design/{issue-key}/01-discovery.md` for user group context and problem framing. +If `.artifacts/ux-design/{issue-key}/02-research.md` exists, read it for +user needs and insights — these inform impact descriptions in the evaluation +findings and the cross-reference step below. + ## Process ### Step 1: Choose Evaluation Depth (Interactive) Ask the researcher what depth of evaluation is appropriate: -| Depth | What it covers | When to use | -|-------|---------------|-------------| -| **Quick** | Rubric scoring only (Completeness, Usability, Feasibility — 0-2 each, max 6, pass >= 5 with no zeros) | Early iterations, rapid feedback | -| **Standard** | Rubric + simulated usability testing with personas (primary, power, infrequent user) + 4-8 task scenarios + severity-ranked issues | Most evaluations | -| **Full** | Standard + desirability study (word association, emotional response mapping, desirability score 1-10) | Final evaluation before handoff | +| Depth | What it covers | Skills run | +|-------|---------------|-----------| +| **Quick** | Multi-evaluator heuristic inspection only (three independent AI evaluators surface usability violations against the chosen framework). No design scoring, no simulated usability. | `uxd-research-heuristic-eval` (Step 2) | +| **Standard** | Quick + structured design-heuristics scoring (accessibility, visual hierarchy, content, state coverage, goal alignment) + simulated usability testing with personas and 4-8 task scenarios, severity-ranked. | Steps 2, 3, 4 (`--depth standard`) | +| **Full** | Standard + desirability study (word association, emotional response mapping, desirability score 1-10). | Steps 2, 3, 4 (`--depth full`) | + +Use Quick for early iterations and rapid feedback, Standard for most +evaluations, and Full for the final evaluation before handoff. Default to **Standard** unless the researcher specifies otherwise. -If a selected depth's tools are unavailable, note "Tool unavailable — depth -downgraded to Standard" and confirm with the researcher before proceeding. +**Naming caution:** this workflow's Quick/Standard/Full tier is *not* the same +thing as `uxd-prototype-evaluate`'s own `--depth quick|standard|full`. The +workflow tier decides *which skills run* (Quick runs no `uxd-prototype-evaluate` +at all); the skill's `--depth` only tunes that one skill once it does run. When +this phase runs `uxd-prototype-evaluate` (Standard/Full), it passes +`--depth standard` or `--depth full` accordingly (Step 4) — don't confuse the +two scales. -### Step 2: Heuristic Evaluation +If the selected depth requires tools that are unavailable, stop and tell +the researcher to run `./install.sh` before proceeding. -Run `/uxd-workshop:uxd-research-heuristic-eval` against the prototype. -This is the primary evaluation tool — tested with an eval suite. +### Step 2: Heuristic Evaluation -This skill uses three independent AI-simulated evaluators: +This is the primary evaluation tool — tested with an eval suite. It uses three +independent AI-simulated evaluators: - **Evaluator A:** Visual inspection - **Evaluator B:** Task flow analysis - **Evaluator C:** Edge cases and accessibility Findings are reconciled across evaluators and tagged by agreement level -(Unanimous, Majority, Single). Evaluators report **violations only** — -they do not assign severity or make design recommendations. The researcher -assigns severity during review. +(Unanimous, Majority, Single). Evaluators report **violations only** — they do +not make design recommendations. -**Framework selection:** The skill will ask which heuristic framework to -use — do not default silently. Available frameworks: +**Framework selection first.** Ask the researcher which heuristic framework to +use before running the skill — do not default silently. Available frameworks: - Nielsen's 10 Usability Heuristics - Shneiderman's 8 Golden Rules - ISO 9241-110 Interaction Principles - Gerhardt-Powals' Cognitive Engineering Principles -If this skill is not available, perform a manual heuristic inspection -using Nielsen's 10 as the default framework. +**Produce the evaluation input first.** `uxd-research-heuristic-eval` inspects +screenshots, a URL, or a text description — **not** Figma links or raw HTML file +paths. So before invoking it, turn the prototype into something the skill can +see: + +- **Standalone HTML** (`03-prototype/prototype/`): serve it and pass the URL. + From the prototype directory, start a local server in the background, e.g. + `python3 -m http.server 8000` (run from + `.artifacts/ux-design/{issue-key}/03-prototype/prototype/`), then pass + `http://localhost:8000/.html`. Stop the server when the skill finishes. +- **Screenshots** (any mode, or when a server can't run): capture one image per + key screen/state (empty, loading, error, populated) into + `04-eval-raw/screenshots/` — via a browser automation tool if available, or + ask the researcher to export them — and pass that directory. +- **Workspace mode:** the prototype runs inside the codebase; serve or run the + app per the project's own instructions and pass the URL, or use screenshots. + +**Screenshots are mandatory at Standard/Full depth.** A served URL alone +satisfies *this* step (Step 2), but Step 3's `uxd-evaluate-design-heuristics` +requires **screenshots specifically** and will stop and ask if none are provided +(it evaluates visual context and does not accept a URL). So whenever the chosen +depth is Standard or Full, capture the screenshots into `04-eval-raw/screenshots/` +now — even if you also serve a URL for Step 2 — so Step 3 has its required input +and can't block mid-phase after `uxd-prototype-evaluate` scratch is already set +up. At Quick depth (Step 2 only) a URL alone is sufficient. + +**Gate — no fabricated input.** If you cannot produce the required input — +a URL *or* screenshots at Quick depth, and **screenshots** at Standard/Full depth +(e.g. an unattended run with no browser/serving capability and no exported +images) — **stop and tell the researcher** what is needed. Do not run any skill +against a Figma link or a raw file path, and do not describe the prototype from +memory in place of real input — either would produce an evaluation of something +other than the prototype. + +**Invocation.** Run the skill in agent-operated mode so its own researcher gate +is deferred to this workflow's single combined gate in Step 7: -### Step 3: Design Heuristics Scoring (Optional) +``` +/uxd-research-heuristic-eval \ + --framework --review none \ + --project .artifacts/ux-design/{issue-key}/04-eval-raw +``` + +`--review none` requires `--framework` (it activates the skill's Mode B), so +always pass the framework the researcher chose. With `--review none` the skill +emits an **Unreviewed Draft** with AI-*suggested* severities and skips its own +review gate — this is intentional. We do **not** run two researcher gates; the +single human gate is Step 7 below, over the combined findings from all methods. + +`--project` directs the skill's `.md`/`.html` reports to +`.artifacts/ux-design/{issue-key}/04-eval-raw/` (otherwise it writes them to +the current working directory). Read that report in Step 6 to fold the findings +into `04-evaluation.md`. -If available, run `/uxd-workshop:uxd-evaluate-design-heuristics` for -structured scoring across dimensions: +### Step 3: Design Heuristics Scoring (Standard and Full depth only) + +Run the `uxd-evaluate-design-heuristics` skill for structured scoring +across dimensions: - Accessibility compliance - Visual hierarchy and scannability @@ -71,36 +140,127 @@ structured scoring across dimensions: - State coverage (empty, loading, error, populated) - Goal alignment -Returns a Pass/Fail verdict with per-dimension scores (1-5), a critical -issues list, and an optional full report. - -If this skill is not available, skip this step. - -### Step 4: Simulated Usability Assessment +**Input: the screenshots captured in Step 2.** This skill requires +**screenshots** (it evaluates visual context and, unlike +`uxd-research-heuristic-eval`, does not accept a served URL); it stops and asks +if none are given. Pass it the `04-eval-raw/screenshots/` directory produced in +Step 2. Since Step 2's gate makes screenshots mandatory at Standard/Full depth, +they are already present; if for any reason they are not, capture them (or ask +the researcher to export them) before invoking — do not run this skill against a +URL or from memory. + +**Output is returned inline — there is no report file.** This skill is a pure +LLM skill (no `scripts/`, no `--project` flag): it *returns* the Pass/Fail +verdict, per-dimension scores (1-5), and critical issues directly (its `report` +flag, default `true`, adds the full write-up to the same returned output, it does +not write a file). Nothing lands on disk, so there is nothing to mirror or clean +up here. Capture the returned scores and critical issues in memory and fold them +into `04-evaluation.md` in Step 6. + +### Step 4: Simulated Usability Assessment (Standard and Full depth only) + +Skip this step at Quick depth. + +`uxd-prototype-evaluate` reads its inputs from the **native skill layout**, +`.artifacts/{ID}/`, not from our `03-prototype/` directory. It reads different +files by mode: +- **Standalone mode:** the prototype files in `.artifacts/{ID}/prototype/`, + `.artifacts/{ID}/rfe-snapshot.md`, and `.artifacts/{ID}/metadata.json`. +- **Workspace mode:** `.artifacts/{ID}/changeset.md` and + `.artifacts/{ID}/workspace-analysis.json` (plus `metadata.json`). + +If you invoke it without staging these, it silently finds nothing and produces +wrong or unevaluable results. Before running it: + +1. Read the **skill prototype ID** (`{ID}`) recorded in + `.artifacts/ux-design/{issue-key}/03-prototype/prototype-notes.md`. +2. Ensure `.artifacts/{ID}/` contains the skill's expected layout. In a + continued session only our mirror under `03-prototype/` remains (Step 3 of + `/prototype` removes the native copy), so recreate it. The mirror preserves + the native layout, so this is a structure-preserving copy of whichever set + applies: + - **Standalone:** `03-prototype/prototype/` → `.artifacts/{ID}/prototype/`; + `03-prototype/rfe-snapshot.md` → `.artifacts/{ID}/rfe-snapshot.md`; + `03-prototype/metadata.json` → `.artifacts/{ID}/metadata.json` + - **Workspace:** `03-prototype/changeset.md` → `.artifacts/{ID}/changeset.md`; + `03-prototype/workspace-analysis.json` → + `.artifacts/{ID}/workspace-analysis.json`; + `03-prototype/metadata.json` → `.artifacts/{ID}/metadata.json` + - Copy `03-prototype/reviews/summary.md` back to `.artifacts/{ID}/reviews/` + too if it exists from a prior evaluation (so refinement can find it). +3. Invoke the skill with the ID and matching depth: -If the chosen depth is **Standard** or **Full**, run -`/uxd-workshop:uxd-prototype-evaluate` at the matching depth: +``` +/uxd-prototype-evaluate {ID} --depth {standard|full} +``` - **Standard:** Rubric scoring + simulated usability testing with personas and task scenarios, severity-ranked issues (S1 critical through S4 enhancement) - **Full:** Standard + desirability study -If this skill is not available, simulate usability scenarios manually: -define 3 personas (primary, power, infrequent user), 4-6 task scenarios, -and walk through each against the prototype. +The skill writes its outputs under `.artifacts/{ID}/` (`reviews/summary.md`, +`report-usability.md`, and for Full `report-desirability.md`) and a +`pipeline-report.html` at the **`.artifacts/` root** — both *outside* our +namespace. Read those in Step 6 to fold results into `04-evaluation.md`, then: + +- **Mirror the canonical outputs into our namespace:** copy + `.artifacts/{ID}/reviews/summary.md` → `03-prototype/reviews/summary.md` + (refinement re-reads this), `report-usability.md` and any + `report-desirability.md` → `04-eval-raw/`, and `.artifacts/pipeline-report.html` + → `04-eval-raw/pipeline-report.html`. +- **Clean up skill scratch (artifact isolation).** Once mirrored, remove the + native `.artifacts/{ID}/` and the stray `.artifacts/pipeline-report.html` so + nothing is left outside `.artifacts/ux-design/` (`AGENTS.md` rule). A later + session recreates `.artifacts/{ID}/` from the mirror as in step 2 above. + +This skill's usability dimension also evaluates against Nielsen's heuristics, +which overlaps with Step 2 when the researcher chose Nielsen there. The overlap +is intentional — two independent passes (one violation-focused, one task/persona +-focused) raise confidence in findings both flag. Note convergent findings as +higher-confidence in Step 6 rather than deduplicating them away. + +**Runtime note:** `uxd-prototype-evaluate` runs Python helper scripts via +`python3 ${CLAUDE_SKILL_DIR}/scripts/...`. `CLAUDE_SKILL_DIR` is set by Claude +Code; under Cursor or Gemini it is unset. Before the skill runs those helpers, +check it (`printenv CLAUDE_SKILL_DIR`). If it is empty, resolve the skill's +directory from the deterministic install path +`${HOME}/.uxd-ai-skills/plugins/uxd-workshop/skills/uxd-prototype-evaluate` and +substitute that path inline for every `${CLAUDE_SKILL_DIR}` in the command +(e.g. `CLAUDE_SKILL_DIR= python3 /scripts/