From 6a72e1068de7ddc8ffd967b090dcd056a17f2c8d Mon Sep 17 00:00:00 2001 From: Jeff Puzzo Date: Thu, 13 Aug 2026 14:10:42 -0400 Subject: [PATCH 1/2] UXDOPS-2843: Add /research workflow with UXD marketplace skill integration --- AGENTS.md | 2 + README.md | 3 + install.sh | 61 +++++++++ research/README.md | 121 +++++++++++++++++ research/SKILL.md | 26 ++++ research/commands/evaluate.md | 11 ++ research/commands/handoff.md | 11 ++ research/commands/ingest.md | 11 ++ research/commands/investigate.md | 11 ++ research/commands/prototype.md | 11 ++ research/guidelines.md | 64 +++++++++ research/skills/controller.md | 185 ++++++++++++++++++++++++++ research/skills/evaluate.md | 217 +++++++++++++++++++++++++++++++ research/skills/handoff.md | 178 +++++++++++++++++++++++++ research/skills/ingest.md | 107 +++++++++++++++ research/skills/investigate.md | 157 ++++++++++++++++++++++ research/skills/prototype.md | 159 ++++++++++++++++++++++ 17 files changed, 1335 insertions(+) create mode 100644 research/README.md create mode 100644 research/SKILL.md create mode 100644 research/commands/evaluate.md create mode 100644 research/commands/handoff.md create mode 100644 research/commands/ingest.md create mode 100644 research/commands/investigate.md create mode 100644 research/commands/prototype.md create mode 100644 research/guidelines.md create mode 100644 research/skills/controller.md create mode 100644 research/skills/evaluate.md create mode 100644 research/skills/handoff.md create mode 100644 research/skills/ingest.md create mode 100644 research/skills/investigate.md create mode 100644 research/skills/prototype.md diff --git a/AGENTS.md b/AGENTS.md index 8b1c10e..75fd9d7 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) +- **research** — UX research workflow (ingest, investigate, prototype, evaluate, handoff) - **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 @@ -161,6 +162,7 @@ ai-workflows/ ├── implement/ ├── kcs/ ├── prd/ +├── research/ ├── rebase-stack/ ├── sizing/ ├── skill-reviewer/ diff --git a/README.md b/README.md index 8056e77..82174d7 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ Reusable AI coding workflows a team member can install globally or per-project, - **Design** -- Design-and-decompose workflow: ingest a PRD, draft a technical design document, decompose into Jira-ready epics and stories, revise based on feedback, publish as a GitHub PR, respond to reviewer comments, and sync epics/stories to Jira. See [design/README.md](design/README.md). +- **Research** -- UX research workflow: ingest a feature request, investigate through user research, generate prototypes, run heuristic evaluation, and produce a validated design handoff. Uses skills from the [UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). + See [research/README.md](research/README.md). + - **Implement** -- Story-to-code workflow: take a Jira Story, plan the implementation, write contract-based tests and production code via TDD, validate against the project's CI expectations, and manage review via GitHub PRs. See [implement/README.md](implement/README.md). diff --git a/install.sh b/install.sh index 8bba840..f7582b3 100755 --- a/install.sh +++ b/install.sh @@ -122,6 +122,49 @@ 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_MARKETPLACE="rh-uxd/ai-helpers" + +# UXD AI Skills — plugins used by workflows. +# uxd-workshop: research/* +UXD_PLUGINS=(uxd-workshop) + +ensure_uxd_repo() { + if [[ -d "$UXD_DIR" ]]; then + echo " UXD AI Skills repo already cloned at $UXD_DIR" + return + fi + 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; skipping" >&2 + return 1 + } +} + +install_uxd_skills() { + local skills_dir="$1" + ensure_uxd_repo || return + + for plugin in "${UXD_PLUGINS[@]}"; do + local plugin_skills + if [[ "$plugin" == pf-* ]]; then + plugin_skills="${UXD_DIR}/plugins/patternfly/${plugin}/skills" + else + plugin_skills="${UXD_DIR}/plugins/${plugin}/skills" + fi + [[ -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 @@ -194,6 +237,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() { @@ -268,6 +312,22 @@ install_claude() { echo " Removed stale commands symlink ${CMDS_DIR}/${wf} ($SCOPE)" fi done + + # Install UXD AI Skills — marketplace (preferred) with symlink fallback. + if command -v claude &>/dev/null; then + if ! claude plugins marketplace list 2>/dev/null | grep -q "uxd-ai-helpers"; then + echo " Adding UXD AI Skills marketplace..." + claude plugins marketplace add "$UXD_MARKETPLACE" 2>/dev/null || true + fi + for plugin in "${UXD_PLUGINS[@]}"; do + if ! claude plugins list 2>/dev/null | grep -q "$plugin"; then + echo " Installing ${plugin} plugin (UXD AI Skills)..." + claude plugins install "${plugin}@uxd-ai-helpers" 2>/dev/null || true + fi + done + else + install_uxd_skills "$SKILLS_DIR" + fi } install_gemini() { @@ -283,6 +343,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" } # --- main --- diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..56724b6 --- /dev/null +++ b/research/README.md @@ -0,0 +1,121 @@ +# Research Workflow + +A UX research workflow that takes a feature request through discovery, user research, prototyping, and heuristic evaluation to produce a validated design handoff artifact for implementation. + +## Phase Flow + +```mermaid +graph TD + ingest([ingest]) --> investigate + investigate --> prototype + prototype --> evaluate + evaluate -->|iterate| prototype + evaluate -->|ready| handoff +``` + +## Prerequisites + +| Tool | Required | Purpose | +|------|----------|---------| +| Jira access (MCP or CLI) | For `/ingest` | Fetch issue details for problem framing | +| UXD marketplace plugins | For `/prototype`, `/evaluate` | Prototyping and heuristic evaluation | + +## Phases + +| Phase | Command | Purpose | Artifact(s) | +|-------|---------|---------|-------------| +| Ingest | `/ingest` | Frame the problem, identify user groups, survey landscape | `01-discovery.md` | +| Investigate | `/investigate` | 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` | + +## Typical Flow + +```text +/ingest EDM-1234 + → frames the problem, identifies user groups + → surveys competitive landscape + → writes .artifacts/research/EDM-1234/01-discovery.md + +/investigate + → conducts user research (interviews, surveys, analytics) + → synthesizes findings into themed insights + → writes 02-research.md + +/prototype + → generates design prototypes informed by research + → uses uxd-prototype-create skill when available + → writes 03-prototype/ (files + prototype-notes.md) + +/evaluate + → runs heuristic evaluation against prototype + → uses uxd-research-heuristic-eval skill when available + → 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 + → writes 05-handoff.md +``` + +## Artifacts + +All artifacts are stored in `.artifacts/research/{issue-key}/`. + +```text +.artifacts/research/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) +``` + +## UXD Marketplace Skills + +This workflow uses skills from the [UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). All skills degrade gracefully — the workflow functions without them. + +| Skill | Plugin | Used by | +|-------|--------|---------| +| `uxd-research-heuristic-eval` | `uxd-workshop` | `/evaluate` | +| `uxd-evaluate-design-heuristics` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-create` | `uxd-workshop` | `/prototype` | +| `uxd-figma-read` | `uxd-workshop` | `/prototype` | + +## Directory Structure + +```text +research/ +├── 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 +│ ├── investigate.md # Conduct user research +│ ├── prototype.md # Generate design prototypes +│ ├── evaluate.md # Heuristic evaluation +│ └── handoff.md # Design-to-implementation spec +└── commands/ + ├── ingest.md # /ingest command + ├── investigate.md # /investigate command + ├── prototype.md # /prototype command + ├── evaluate.md # /evaluate command + └── handoff.md # /handoff command +``` + +## Getting Started + +```bash +# Install the workflow +./install.sh claude --workflows research + +# Or install all workflows +./install.sh all +``` + +Then in your project, run the `research` workflow's `ingest` command for your Jira issue or feature description. diff --git a/research/SKILL.md b/research/SKILL.md new file mode 100644 index 0000000..caf9182 --- /dev/null +++ b/research/SKILL.md @@ -0,0 +1,26 @@ +--- +name: research +version: 0.1.0 +description: >- + UX research workflow that takes a feature request through discovery, + user research, prototyping, and heuristic evaluation to produce a + validated design handoff artifact for implementation. + Use when conducting UX research, creating prototypes for evaluation, + running heuristic evaluations, or preparing design handoffs. + Activated by commands: /ingest, /investigate, /prototype, /evaluate, /handoff. +--- +# Research Workflow Orchestrator + +## Quick Start + +1. If the user invoked a specific command (e.g., `/prototype`, `/evaluate`), + read `skills/{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/research/commands/evaluate.md b/research/commands/evaluate.md new file mode 100644 index 0000000..45c21b7 --- /dev/null +++ b/research/commands/evaluate.md @@ -0,0 +1,11 @@ +--- +name: research: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/research/commands/handoff.md b/research/commands/handoff.md new file mode 100644 index 0000000..6b62283 --- /dev/null +++ b/research/commands/handoff.md @@ -0,0 +1,11 @@ +--- +name: research: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/research/commands/ingest.md b/research/commands/ingest.md new file mode 100644 index 0000000..33fc51f --- /dev/null +++ b/research/commands/ingest.md @@ -0,0 +1,11 @@ +--- +name: research: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/research/commands/investigate.md b/research/commands/investigate.md new file mode 100644 index 0000000..f03fe30 --- /dev/null +++ b/research/commands/investigate.md @@ -0,0 +1,11 @@ +--- +name: research:investigate +description: "Conduct user research, gather data, and synthesize findings into insights" +--- +# /investigate + +Read `../skills/controller.md` and follow it. + +Dispatch the **investigate** phase. Context: + +$ARGUMENTS diff --git a/research/commands/prototype.md b/research/commands/prototype.md new file mode 100644 index 0000000..9364d26 --- /dev/null +++ b/research/commands/prototype.md @@ -0,0 +1,11 @@ +--- +name: research: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/research/guidelines.md b/research/guidelines.md new file mode 100644 index 0000000..b92034e --- /dev/null +++ b/research/guidelines.md @@ -0,0 +1,64 @@ +# Research 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. + +## 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 frontmatter. +- 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/research/skills/controller.md b/research/skills/controller.md new file mode 100644 index 0000000..34075ea --- /dev/null +++ b/research/skills/controller.md @@ -0,0 +1,185 @@ +--- +name: controller +description: Top-level workflow controller that manages phase transitions for UX research, prototyping, and design handoff. +--- + +# Research Workflow Controller + +You are the workflow controller. Your job is to manage the research 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. **Investigate** (`/investigate`) — `investigate.md` + Conduct user research — interviews, surveys, analytics, desk research. + Synthesize findings into insights and design recommendations. + +3. **Prototype** (`/prototype`) — `prototype.md` + Generate design prototypes informed by 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, and acceptance criteria. + +## Workspace + +All work happens in the **source repo** — the researcher needs codebase +context to make informed design decisions. Planning artifacts live in +`.artifacts/research/{issue-key}/` (gitignored). + +### Artifact directory + +All working artifacts are stored in `.artifacts/research/{issue-key}/` +within the source repo: + +| Artifact | File | Written by | +|----------|------|------------| +| Discovery brief | `01-discovery.md` | `/ingest` | +| Research findings | `02-research.md` | `/investigate` | +| 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` | + +## How to Execute a Phase + +1. **Announce** the phase to the user: *"Starting /investigate."* +2. **Locate** the skill file — read and follow + `../../_shared/recipes/phase-override-resolution.md` with + WORKFLOW=`research`, 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 → investigate → prototype → evaluate → (iterate? → prototype) or → handoff +``` + +### What to Recommend + +**Continuing forward:** + +- `/ingest` completed → recommend `/investigate` (almost always the right next step) +- `/investigate` 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 → the research workflow is done; recommend the user run `/implement` on the handoff artifact + +**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:** + +- `/investigate` reveals the problem framing is wrong → suggest revisiting `/ingest` +- `/prototype` reveals research gaps → suggest additional `/investigate` work +- `/evaluate` reveals fundamental design problems → suggest `/prototype` with specific changes +- `/handoff` reveals missing interaction specs → loop back to refine the prototype + +**Skipping:** + +- If the researcher already has research data, they may start at `/prototype` +- 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 | +| `/investigate` | `01-discovery.md` (or equivalent problem framing) | +| `/prototype` | `02-research.md` (or equivalent research findings) | +| `/evaluate` | `03-prototype/` (prototype to evaluate) | +| `/handoff` | `04-evaluation.md` (or researcher confirms design is ready) | + +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: +- /investigate — if you want to gather more research data first +- /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. + +## 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/research/{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/research/skills/evaluate.md b/research/skills/evaluate.md new file mode 100644 index 0000000..81fe056 --- /dev/null +++ b/research/skills/evaluate.md @@ -0,0 +1,217 @@ +--- +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/research/{issue-key}/03-prototype/prototype-notes.md` +for design decisions and open questions. If the prototype directory doesn't +exist, tell the researcher that `/prototype` should run first and stop. + +Also read `02-research.md` for user needs that the prototype should address +and `01-discovery.md` for user group context. + +## 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. + +### 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/research/{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/research/skills/handoff.md b/research/skills/handoff.md new file mode 100644 index 0000000..80b88e4 --- /dev/null +++ b/research/skills/handoff.md @@ -0,0 +1,178 @@ +--- +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 research workflow and `/implement`. + +## Prerequisites + +Read all prior artifacts: +- `.artifacts/research/{issue-key}/01-discovery.md` — problem context +- `.artifacts/research/{issue-key}/02-research.md` — user needs and insights +- `.artifacts/research/{issue-key}/03-prototype/prototype-notes.md` — design decisions +- `.artifacts/research/{issue-key}/04-evaluation.md` — evaluation results + +If `04-evaluation.md` doesn't exist, ask the researcher: "No evaluation +artifact found. Want to run `/evaluate` first, or proceed with handoff +based on the current prototype?" + +## 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: 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 + +### Step 5: 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 + +## Output + +`.artifacts/research/{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} | + +## Accessibility Requirements + +{From evaluation findings — specific a11y requirements} + +- {requirement with WCAG reference} +- ... + +## Acceptance Criteria + +| # | Criterion | Traces to | +|---|-----------|-----------| +| AC1 | {testable criterion} | {Insight #N / User Need #N} | +| AC2 | {testable criterion} | {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 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/research/skills/ingest.md b/research/skills/ingest.md new file mode 100644 index 0000000..65a678f --- /dev/null +++ b/research/skills/ingest.md @@ -0,0 +1,107 @@ +--- +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 research +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. + +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 Research Questions + +Based on the problem and landscape, identify the open questions that +user research should answer: + +- What do we not know about user needs? +- Where do our assumptions need validation? +- What usability risks exist in the current approaches? + +## Output + +`.artifacts/research/{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} +... + +## Research Questions + +1. {Specific, answerable question} +2. {Specific, answerable question} +... + +## 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 +research questions missing?" + +Wait for confirmation. Then **re-read the controller** (`controller.md`) +for next-step guidance. diff --git a/research/skills/investigate.md b/research/skills/investigate.md new file mode 100644 index 0000000..cc7dcc3 --- /dev/null +++ b/research/skills/investigate.md @@ -0,0 +1,157 @@ +--- +name: investigate +description: User research, data gathering, and synthesis into insights and design recommendations. +--- + +# Investigate — 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/research/{issue-key}/01-discovery.md` for the problem +framing and research questions. 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 research questions, propose a research plan: + +- **Methods** — which research methods fit each question? (interviews, + surveys, analytics review, support ticket analysis, diary studies) +- **Participants** — who should be included? How many? +- **Data sources** — what existing data can the AI analyze directly? + (support tickets, analytics dashboards, existing survey results, forum posts) + +Present the plan to the researcher. Wait for confirmation before proceeding. + +The researcher knows their constraints — they may have 3 users available, +not 12. 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 +- Review analytics data if accessible +- 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/research/{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: {question from discovery} +**Finding:** {what we learned} +**Evidence:** {data points, quotes, sources} +**Confidence:** {HIGH/MEDIUM/LOW} + +### Q2: {question 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} | + +## 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/research/skills/prototype.md b/research/skills/prototype.md new file mode 100644 index 0000000..d0ab638 --- /dev/null +++ b/research/skills/prototype.md @@ -0,0 +1,159 @@ +--- +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/research/{issue-key}/02-research.md` for research findings +and design recommendations. If it doesn't exist, tell the researcher that +`/investigate` should run first and stop. + +Also read `01-discovery.md` for problem context and competitive landscape. + +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 research findings and design recommendations from `/investigate` | +| **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 research insight to one or more user stories +- Include acceptance criteria derived from research findings +- Prioritize stories by user need priority from `02-research.md` + +Save to `.artifacts/research/{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. + +### 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/research/{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. From 2d45986abd9847042b0018ce8f1da13721f4aa78 Mon Sep 17 00:00:00 2001 From: Jeff Puzzo Date: Fri, 14 Aug 2026 16:54:30 -0400 Subject: [PATCH 2/2] UXDOPS-2843: Rename to ux-design, cut /research phase, add lifecycle phases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Structural changes from PR review: - Rename research/ → ux-design/ and all internal references - Cut /research phase — designer brings research context, synthesis skill deferred pending UXD research team scoping - Add /revise, /publish, /respond lifecycle phases (adapted from design/) - Renumber artifacts: 01-discovery, 02-prototype/, 03-evaluation, 04-handoff, 05-pr-description - Add publish.md Step 5 (Prepare PR Description) matching prd pattern - Wire uxd-discovery and uxd-design-handoff via override files - Update AGENTS.md: ux-design with 7-phase list, fix directory tree install.sh: - Drop marketplace-specific Claude install block - Scope UXD install to ux-design workflow via workflow_selected() - Add -o pipefail for safer error handling (skip -u for bash 3.2 compat) 7 phases, all fully owned: ingest → prototype ⟷ evaluate → handoff → revise → publish → respond --- .workflows/code-review/skills/start.md | 42 +++++ .workflows/design/skills/draft.md | 52 ++++++ .workflows/design/skills/research.md | 66 +++++++ .workflows/implement/skills/code.md | 51 ++++++ .workflows/implement/skills/validate.md | 45 +++++ .workflows/ux-design/skills/handoff.md | 42 +++++ .workflows/ux-design/skills/ingest.md | 43 +++++ AGENTS.md | 4 +- install.sh | 36 ++-- research/README.md | 121 ------------- research/commands/investigate.md | 11 -- research/skills/investigate.md | 157 ----------------- ux-design/README.md | 139 +++++++++++++++ {research => ux-design}/SKILL.md | 18 +- {research => ux-design}/commands/evaluate.md | 2 +- {research => ux-design}/commands/handoff.md | 2 +- {research => ux-design}/commands/ingest.md | 2 +- {research => ux-design}/commands/prototype.md | 2 +- ux-design/commands/publish.md | 11 ++ ux-design/commands/respond.md | 11 ++ ux-design/commands/revise.md | 11 ++ {research => ux-design}/guidelines.md | 9 +- {research => ux-design}/skills/controller.md | 77 ++++---- {research => ux-design}/skills/evaluate.md | 10 +- {research => ux-design}/skills/handoff.md | 25 ++- {research => ux-design}/skills/ingest.md | 6 +- {research => ux-design}/skills/prototype.md | 28 +-- ux-design/skills/publish.md | 164 ++++++++++++++++++ ux-design/skills/respond.md | 121 +++++++++++++ ux-design/skills/revise.md | 78 +++++++++ 30 files changed, 995 insertions(+), 391 deletions(-) create mode 100644 .workflows/code-review/skills/start.md create mode 100644 .workflows/design/skills/draft.md create mode 100644 .workflows/design/skills/research.md create mode 100644 .workflows/implement/skills/code.md create mode 100644 .workflows/implement/skills/validate.md create mode 100644 .workflows/ux-design/skills/handoff.md create mode 100644 .workflows/ux-design/skills/ingest.md delete mode 100644 research/README.md delete mode 100644 research/commands/investigate.md delete mode 100644 research/skills/investigate.md create mode 100644 ux-design/README.md rename {research => ux-design}/SKILL.md (53%) rename {research => ux-design}/commands/evaluate.md (89%) rename {research => ux-design}/commands/handoff.md (89%) rename {research => ux-design}/commands/ingest.md (90%) rename {research => ux-design}/commands/prototype.md (88%) create mode 100644 ux-design/commands/publish.md create mode 100644 ux-design/commands/respond.md create mode 100644 ux-design/commands/revise.md rename {research => ux-design}/guidelines.md (89%) rename {research => ux-design}/skills/controller.md (66%) rename {research => ux-design}/skills/evaluate.md (95%) rename {research => ux-design}/skills/handoff.md (85%) rename {research => ux-design}/skills/ingest.md (91%) rename {research => ux-design}/skills/prototype.md (83%) create mode 100644 ux-design/skills/publish.md create mode 100644 ux-design/skills/respond.md create mode 100644 ux-design/skills/revise.md diff --git a/.workflows/code-review/skills/start.md b/.workflows/code-review/skills/start.md new file mode 100644 index 0000000..6207430 --- /dev/null +++ b/.workflows/code-review/skills/start.md @@ -0,0 +1,42 @@ +--- +name: start +description: Code review with PatternFly compliance checks for UI changes. +--- + +# Code Review — with UXD Checks + +This override wraps the built-in code review start phase and adds PatternFly +compliance checks for PRs that touch UI code. + +## Step 1: Run Built-in Code Review + +Read and execute the built-in code review skill at +`../../../code-review/skills/start.md`. + +Complete the full review process as usual. + +## Step 2: UXD Review (conditional) + +After the built-in review completes, check whether the PR touches UI code: + +**Run this step when ANY of the following are true:** +- Changed files include `.tsx`, `.jsx`, `.css`, or `.scss` extensions +- Changed files import from `@patternfly/*` packages + +**Skip this step when:** +- No files match the above criteria + +### If running: + +Run `/pf-code-review:pf-review`. If this skill is not available, skip this step. + +Add UXD findings as a separate section in the review output. + +### If skipping: + +Continue without UXD checks. + +## When This Phase Is Done + +Present combined review findings — standard code review plus UXD checks (if run). +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/design/skills/draft.md b/.workflows/design/skills/draft.md new file mode 100644 index 0000000..e3d3399 --- /dev/null +++ b/.workflows/design/skills/draft.md @@ -0,0 +1,52 @@ +--- +name: draft +description: Design document drafting with PatternFly compliance check for PF-based UIs. +--- + +# Design Draft — with PatternFly Compliance + +This override wraps the built-in design draft phase and adds a PatternFly +compliance check for features that use PatternFly components. + +## Step 1: Run Built-in Draft + +Read and execute the built-in draft skill at +`../../../design/skills/draft.md`. + +Follow every stage — outline, draft, review, and revision. Write the design +document to `.artifacts/design/{issue-key}/03-design.md` as usual. + +## Step 2: PatternFly Compliance Check (conditional) + +After the design document is drafted, check whether the feature uses +PatternFly components: + +**Run this step when ANY of the following are true:** +- The design references PatternFly components (Page, Table, Modal, Toolbar, etc.) +- The codebase imports from `@patternfly/*` packages +- The feature modifies existing PatternFly-based UI + +**Skip this step when:** +- No PatternFly components are referenced or imported +- The feature is backend-only + +### If running: + +Run `/pf-code-review:pf-review`. If this skill is not available, skip this step. + +Append findings to the design document: + +```markdown +## PatternFly Compliance + +{compliance findings from pf-review} +``` + +### If skipping: + +Continue without PatternFly compliance check. + +## When This Phase Is Done + +Report the design document with compliance results (if run). +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/design/skills/research.md b/.workflows/design/skills/research.md new file mode 100644 index 0000000..368f8da --- /dev/null +++ b/.workflows/design/skills/research.md @@ -0,0 +1,66 @@ +--- +name: research +description: Design research with UXD heuristic evaluation for UI-facing features. +--- + +# Design Research — with UXD Evaluation + +This override wraps the built-in design research phase and adds a UXD +heuristic evaluation step for features with a user-facing interface. + +## Step 1: Run Built-in Research + +Read and execute the built-in research skill at +`../../../design/skills/research.md`. + +Follow every stage — scope, plan, iterative research execution, synthesis, +and user presentation. Write findings to +`.artifacts/design/{issue-key}/02-research.md` as usual. + +Do not skip or abbreviate any part of the built-in process. + +## Step 2: UX Heuristic Evaluation (conditional) + +After the built-in research completes and the user approves the findings, +check whether this feature has a user-facing interface: + +**Run this step when ANY of the following are true:** +- The PRD describes new screens, pages, or views +- The PRD modifies existing UI workflows or navigation +- Wireframes, mockups, or screenshots exist in the artifacts or PRD +- The context doc (`01-context.md`) references frontend components + +**Skip this step when:** +- The feature is entirely backend (API, data pipeline, infrastructure) +- No UI surface is described or implied in the PRD + +### If running: + +Gather UI artifacts from the research and PRD — wireframes, mockups, +screenshots, or detailed text descriptions of the proposed interface. + +Run `/uxd-workshop:uxd-research-heuristic-eval` against the gathered +artifacts. If this skill is not available, skip this step. + +When the evaluation completes, append the findings to the research artifact: + +```markdown +## UX Heuristic Evaluation + +{evaluation findings from the heuristic eval skill} +``` + +Save to `.artifacts/design/{issue-key}/02-research.md`. + +Present the combined findings to the user — standard research results plus +heuristic evaluation. Note which usability violations may affect +architectural decisions in the design phase. + +### If skipping: + +Continue without UXD evaluation. + +## When This Phase Is Done + +Report combined findings (standard research + heuristic evaluation if run). +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/implement/skills/code.md b/.workflows/implement/skills/code.md new file mode 100644 index 0000000..a8913ae --- /dev/null +++ b/.workflows/implement/skills/code.md @@ -0,0 +1,51 @@ +--- +name: code +description: Implementation with PatternFly component generation for UI stories. +--- + +# Implement Code — with PatternFly Generation + +This override wraps the built-in implement code phase and adds PatternFly +component generation for stories that involve UI work. + +## Step 1: Run Built-in Code Phase + +Read and execute the built-in code skill at +`../../../implement/skills/code.md`. + +Follow the full TDD cycle — write contract-based tests, then production code. + +## Step 2: PatternFly Component Generation (conditional) + +After the built-in code phase completes, check whether the story involves +PatternFly UI components: + +**Run this step when ANY of the following are true:** +- The story requires new forms, tables, or chart components +- The codebase imports from `@patternfly/*` packages +- The implementation plan references PatternFly components + +**Skip this step when:** +- No UI components are needed +- The story is backend-only + +### If running: + +Use the appropriate PatternFly generator for the component type. +If a skill is not available, skip it. + +- **Forms:** `/pf-react:pf-form-gen` +- **Tables:** `/pf-react:pf-table-gen` +- **Charts:** `/pf-react:pf-chart-gen` + +Run the generator that matches the component type, then integrate the output +into the implementation. + +### If skipping: + +Continue without PatternFly generation. + +## When This Phase Is Done + +Report the implementation with any generated components. +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/implement/skills/validate.md b/.workflows/implement/skills/validate.md new file mode 100644 index 0000000..56cf854 --- /dev/null +++ b/.workflows/implement/skills/validate.md @@ -0,0 +1,45 @@ +--- +name: validate +description: Validation with PatternFly-aware test generation for UI components. +--- + +# Implement Validate — with PatternFly Test Generation + +This override wraps the built-in implement validate phase and adds +PatternFly-aware test generation for UI components. + +## Step 1: Run Built-in Validate Phase + +Read and execute the built-in validate skill at +`../../../implement/skills/validate.md`. + +Complete the full validation — run tests, check CI expectations, verify coverage. + +## Step 2: PatternFly Test Generation (conditional) + +After the built-in validation completes, check whether the implementation +includes PatternFly components that need test coverage: + +**Run this step when ANY of the following are true:** +- New `.tsx` components import from `@patternfly/*` packages +- Existing PatternFly components were modified as part of the story +- Test coverage for PatternFly components is below project thresholds + +**Skip this step when:** +- No PatternFly components were added or modified +- Tests already cover the PatternFly components adequately + +### If running: + +Run `/pf-react:pf-test-gen`. If this skill is not available, skip this step. + +Run the generated tests and verify they pass. + +### If skipping: + +Continue without PatternFly test generation. + +## When This Phase Is Done + +Report validation results including any generated tests. +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/ux-design/skills/handoff.md b/.workflows/ux-design/skills/handoff.md new file mode 100644 index 0000000..30a5703 --- /dev/null +++ b/.workflows/ux-design/skills/handoff.md @@ -0,0 +1,42 @@ +--- +name: handoff +description: Implementation handoff with UXD design-handoff skill enhancement. +--- + +# Handoff — with UXD Design Handoff + +This override wraps the built-in handoff phase and enhances the +implementation spec with the UXD design-handoff skill when available. + +## Step 1: Run Built-in Handoff Phase + +Read and execute the built-in handoff skill at +`../../../ux-design/skills/handoff.md`. + +Complete the full handoff process — component mapping, interaction specs, +state enumeration, acceptance criteria, and research context. + +## Step 2: UXD Design Handoff Enhancement (conditional) + +After the built-in handoff completes, check whether the UXD design-handoff +skill is available: + +Run `/uxd-workshop:uxd-design-handoff` with the handoff artifact +(`04-handoff.md`) as input. If this skill is not available, skip this step. + +### If running: + +Compare the skill's output with the built-in handoff results. Strengthen +`04-handoff.md` with any additions: +- Missing state enumerations the skill identified +- Acceptance criteria gaps +- Component mapping refinements + +### If skipping: + +Continue with the built-in handoff output — it covers the same ground. + +## When This Phase Is Done + +Present the handoff spec to the researcher. +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/.workflows/ux-design/skills/ingest.md b/.workflows/ux-design/skills/ingest.md new file mode 100644 index 0000000..a3375c9 --- /dev/null +++ b/.workflows/ux-design/skills/ingest.md @@ -0,0 +1,43 @@ +--- +name: ingest +description: Problem framing with UXD discovery skill enhancement. +--- + +# Ingest — with UXD Discovery + +This override wraps the built-in ingest phase and enhances problem framing +with the UXD discovery skill when available. + +## Step 1: Run Built-in Ingest Phase + +Read and execute the built-in ingest skill at +`../../../ux-design/skills/ingest.md`. + +Complete the full discovery process as usual — problem framing, user group +identification, competitive landscape, and research questions. + +## Step 2: UXD Discovery Enhancement (conditional) + +After the built-in ingest completes, check whether the UXD discovery skill +is available: + +Run `/uxd-workshop:uxd-discovery` with the same input (Jira issue, feature +description, or problem statement). If this skill is not available, skip +this step. + +### If running: + +Compare the skill's output with the built-in ingest results. Merge any +additional findings into `01-discovery.md`: +- User groups the built-in phase missed +- Competitive examples the skill surfaced +- Research questions worth adding + +### If skipping: + +Continue with the built-in ingest output — it covers the same ground. + +## When This Phase Is Done + +Present the discovery brief to the researcher. +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/AGENTS.md b/AGENTS.md index 75fd9d7..b20424e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +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) -- **research** — UX research workflow (ingest, investigate, prototype, evaluate, handoff) +- **ux-design** — UX design workflow (ingest, 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 @@ -162,7 +162,7 @@ ai-workflows/ ├── implement/ ├── kcs/ ├── prd/ -├── research/ +├── ux-design/ ├── rebase-stack/ ├── sizing/ ├── skill-reviewer/ diff --git a/install.sh b/install.sh index f7582b3..9f19556 100755 --- a/install.sh +++ b/install.sh @@ -19,7 +19,9 @@ # ./install.sh all --project [path] # project-level Cursor + Claude + Gemini # ./install.sh --list # list available workflows -set -e +set -eo pipefail +# Note: -u intentionally omitted — bash 3.2 (macOS default) treats +# "${empty_array[@]}" as unbound, breaking the workflow discovery loop. REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" INSTALL_DIR="${HOME}/.ai-workflows" @@ -127,9 +129,17 @@ UXD_DIR="${HOME}/.uxd-ai-skills" UXD_MARKETPLACE="rh-uxd/ai-helpers" # UXD AI Skills — plugins used by workflows. -# uxd-workshop: research/* +# uxd-workshop: ux-design/* UXD_PLUGINS=(uxd-workshop) +workflow_selected() { + local name="$1" + for wf in "${WORKFLOWS[@]}"; do + [[ "$wf" == "$name" ]] && return 0 + done + return 1 +} + ensure_uxd_repo() { if [[ -d "$UXD_DIR" ]]; then echo " UXD AI Skills repo already cloned at $UXD_DIR" @@ -237,7 +247,9 @@ install_cursor() { echo " Linked ${SKILLS_DIR}/${wf} -> ${INSTALL_DIR}/${wf} ($SCOPE)" done generate_cursor_commands "$CMDS_DIR" - install_uxd_skills "$SKILLS_DIR" + if workflow_selected "ux-design"; then + install_uxd_skills "$SKILLS_DIR" + fi } install_claude() { @@ -313,19 +325,7 @@ install_claude() { fi done - # Install UXD AI Skills — marketplace (preferred) with symlink fallback. - if command -v claude &>/dev/null; then - if ! claude plugins marketplace list 2>/dev/null | grep -q "uxd-ai-helpers"; then - echo " Adding UXD AI Skills marketplace..." - claude plugins marketplace add "$UXD_MARKETPLACE" 2>/dev/null || true - fi - for plugin in "${UXD_PLUGINS[@]}"; do - if ! claude plugins list 2>/dev/null | grep -q "$plugin"; then - echo " Installing ${plugin} plugin (UXD AI Skills)..." - claude plugins install "${plugin}@uxd-ai-helpers" 2>/dev/null || true - fi - done - else + if workflow_selected "ux-design"; then install_uxd_skills "$SKILLS_DIR" fi } @@ -343,7 +343,9 @@ 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" + if workflow_selected "ux-design"; then + install_uxd_skills "$SKILLS_DIR" + fi } # --- main --- diff --git a/research/README.md b/research/README.md deleted file mode 100644 index 56724b6..0000000 --- a/research/README.md +++ /dev/null @@ -1,121 +0,0 @@ -# Research Workflow - -A UX research workflow that takes a feature request through discovery, user research, prototyping, and heuristic evaluation to produce a validated design handoff artifact for implementation. - -## Phase Flow - -```mermaid -graph TD - ingest([ingest]) --> investigate - investigate --> prototype - prototype --> evaluate - evaluate -->|iterate| prototype - evaluate -->|ready| handoff -``` - -## Prerequisites - -| Tool | Required | Purpose | -|------|----------|---------| -| Jira access (MCP or CLI) | For `/ingest` | Fetch issue details for problem framing | -| UXD marketplace plugins | For `/prototype`, `/evaluate` | Prototyping and heuristic evaluation | - -## Phases - -| Phase | Command | Purpose | Artifact(s) | -|-------|---------|---------|-------------| -| Ingest | `/ingest` | Frame the problem, identify user groups, survey landscape | `01-discovery.md` | -| Investigate | `/investigate` | 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` | - -## Typical Flow - -```text -/ingest EDM-1234 - → frames the problem, identifies user groups - → surveys competitive landscape - → writes .artifacts/research/EDM-1234/01-discovery.md - -/investigate - → conducts user research (interviews, surveys, analytics) - → synthesizes findings into themed insights - → writes 02-research.md - -/prototype - → generates design prototypes informed by research - → uses uxd-prototype-create skill when available - → writes 03-prototype/ (files + prototype-notes.md) - -/evaluate - → runs heuristic evaluation against prototype - → uses uxd-research-heuristic-eval skill when available - → 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 - → writes 05-handoff.md -``` - -## Artifacts - -All artifacts are stored in `.artifacts/research/{issue-key}/`. - -```text -.artifacts/research/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) -``` - -## UXD Marketplace Skills - -This workflow uses skills from the [UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). All skills degrade gracefully — the workflow functions without them. - -| Skill | Plugin | Used by | -|-------|--------|---------| -| `uxd-research-heuristic-eval` | `uxd-workshop` | `/evaluate` | -| `uxd-evaluate-design-heuristics` | `uxd-workshop` | `/evaluate` | -| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` | -| `uxd-prototype-create` | `uxd-workshop` | `/prototype` | -| `uxd-figma-read` | `uxd-workshop` | `/prototype` | - -## Directory Structure - -```text -research/ -├── 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 -│ ├── investigate.md # Conduct user research -│ ├── prototype.md # Generate design prototypes -│ ├── evaluate.md # Heuristic evaluation -│ └── handoff.md # Design-to-implementation spec -└── commands/ - ├── ingest.md # /ingest command - ├── investigate.md # /investigate command - ├── prototype.md # /prototype command - ├── evaluate.md # /evaluate command - └── handoff.md # /handoff command -``` - -## Getting Started - -```bash -# Install the workflow -./install.sh claude --workflows research - -# Or install all workflows -./install.sh all -``` - -Then in your project, run the `research` workflow's `ingest` command for your Jira issue or feature description. diff --git a/research/commands/investigate.md b/research/commands/investigate.md deleted file mode 100644 index f03fe30..0000000 --- a/research/commands/investigate.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: research:investigate -description: "Conduct user research, gather data, and synthesize findings into insights" ---- -# /investigate - -Read `../skills/controller.md` and follow it. - -Dispatch the **investigate** phase. Context: - -$ARGUMENTS diff --git a/research/skills/investigate.md b/research/skills/investigate.md deleted file mode 100644 index cc7dcc3..0000000 --- a/research/skills/investigate.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -name: investigate -description: User research, data gathering, and synthesis into insights and design recommendations. ---- - -# Investigate — 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/research/{issue-key}/01-discovery.md` for the problem -framing and research questions. 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 research questions, propose a research plan: - -- **Methods** — which research methods fit each question? (interviews, - surveys, analytics review, support ticket analysis, diary studies) -- **Participants** — who should be included? How many? -- **Data sources** — what existing data can the AI analyze directly? - (support tickets, analytics dashboards, existing survey results, forum posts) - -Present the plan to the researcher. Wait for confirmation before proceeding. - -The researcher knows their constraints — they may have 3 users available, -not 12. 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 -- Review analytics data if accessible -- 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/research/{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: {question from discovery} -**Finding:** {what we learned} -**Evidence:** {data points, quotes, sources} -**Confidence:** {HIGH/MEDIUM/LOW} - -### Q2: {question 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} | - -## 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/README.md b/ux-design/README.md new file mode 100644 index 0000000..771719b --- /dev/null +++ b/ux-design/README.md @@ -0,0 +1,139 @@ +# UX Design Workflow + +A UX design workflow that takes a feature request through discovery, prototyping, and heuristic evaluation to produce a validated design handoff artifact for implementation. + +## Phase Flow + +```mermaid +graph TD + ingest([ingest]) --> prototype + prototype --> evaluate + evaluate -->|iterate| prototype + evaluate -->|ready| handoff + handoff --> revise + revise --> publish + publish --> respond +``` + +## Prerequisites + +| Tool | Required | Purpose | +|------|----------|---------| +| Jira access (MCP or CLI) | Conditional | Required for Jira input, not for feature descriptions | +| UXD marketplace plugins | Optional | Graceful degradation when unavailable | + +## Phases + +| Phase | Command | Purpose | Artifact(s) | +|-------|---------|---------|-------------| +| Ingest | `/ingest` | Frame the problem, identify user groups, survey landscape | `01-discovery.md` | +| Prototype | `/prototype` | Generate design prototypes from discovery | `02-prototype/` | +| Evaluate | `/evaluate` | Heuristic evaluation and usability assessment | `03-evaluation.md` | +| Handoff | `/handoff` | Produce implementation-ready design spec | `04-handoff.md` | +| Revise | `/revise` | Incorporate stakeholder feedback on the handoff spec | `04-handoff.md` (updated) | +| Publish | `/publish` | Push handoff spec as a PR to the docs repo | `05-pr-description.md`, `publish-metadata.json`, PR in docs repo | +| Respond | `/respond` | Fetch and address PR reviewer comments | `04-handoff.md` (updated) | + +## Typical Flow + +```text +/ingest EDM-1234 + → frames the problem, identifies user groups + → surveys competitive landscape + → writes .artifacts/ux-design/EDM-1234/01-discovery.md + +/prototype + → generates design prototypes informed by discovery + → uses uxd-prototype-create skill when available + → writes 02-prototype/ (files + prototype-notes.md) + +/evaluate + → runs heuristic evaluation against prototype + → uses uxd-research-heuristic-eval skill when available + → writes 03-evaluation.md + → loops back to /prototype if critical issues found + +/handoff + → synthesizes all artifacts into implementation spec + → maps UI elements to design system components + → writes 04-handoff.md + +/revise + → incorporates stakeholder feedback on the handoff spec + → maintains consistency across all artifacts + +/publish + → pushes handoff spec as a PR to the docs repo + → creates a draft PR for external review + +/respond + → fetches and addresses PR reviewer comments + → updates handoff spec and docs repo copy +``` + +## 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-prototype/ (prototype files, design rationale) + prototype-notes.md (design decisions, user stories covered) + 03-evaluation.md (heuristic eval report, readiness assessment) + 04-handoff.md (implementation spec, component mapping, AC) + 05-pr-description.md (PR body for docs repo review) + publish-metadata.json (PR number, branch, file paths) +``` + +## UXD Marketplace Skills + +This workflow uses skills from the [UXD AI Skills marketplace](https://github.com/rh-uxd/ai-helpers). All skills degrade gracefully — the workflow functions without them. + +| Skill | Plugin | Used by | +|-------|--------|---------| +| `uxd-discovery` | `uxd-workshop` | `/ingest` | +| `uxd-design-handoff` | `uxd-workshop` | `/handoff` | +| `uxd-research-heuristic-eval` | `uxd-workshop` | `/evaluate` | +| `uxd-evaluate-design-heuristics` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-evaluate` | `uxd-workshop` | `/evaluate` | +| `uxd-prototype-create` | `uxd-workshop` | `/prototype` | +| `uxd-figma-read` | `uxd-workshop` | `/prototype` | + +## 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 +│ ├── prototype.md # Generate design prototypes +│ ├── evaluate.md # Heuristic evaluation +│ ├── handoff.md # Design-to-implementation spec +│ ├── revise.md # Incorporate feedback on handoff spec +│ ├── publish.md # Push handoff spec to docs repo +│ └── respond.md # Address PR reviewer comments +└── commands/ + ├── ingest.md # /ingest 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 the `ux-design` workflow's `ingest` command for your Jira issue or feature description. diff --git a/research/SKILL.md b/ux-design/SKILL.md similarity index 53% rename from research/SKILL.md rename to ux-design/SKILL.md index caf9182..ffdb82e 100644 --- a/research/SKILL.md +++ b/ux-design/SKILL.md @@ -1,20 +1,20 @@ --- -name: research +name: ux-design version: 0.1.0 description: >- - UX research workflow that takes a feature request through discovery, - user research, prototyping, and heuristic evaluation to produce a - validated design handoff artifact for implementation. - Use when conducting UX research, creating prototypes for evaluation, - running heuristic evaluations, or preparing design handoffs. - Activated by commands: /ingest, /investigate, /prototype, /evaluate, /handoff. + UX design workflow that takes a feature request through discovery, + prototyping, and heuristic evaluation to produce a validated design + handoff artifact for implementation. + Use when creating prototypes for evaluation, running heuristic + evaluations, or preparing design handoffs. + Activated by commands: /ingest, /prototype, /evaluate, /handoff, /revise, /publish, /respond. --- -# Research Workflow Orchestrator +# UX Design Workflow Orchestrator ## Quick Start 1. If the user invoked a specific command (e.g., `/prototype`, `/evaluate`), - read `skills/{command}.md` and follow it. + 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 diff --git a/research/commands/evaluate.md b/ux-design/commands/evaluate.md similarity index 89% rename from research/commands/evaluate.md rename to ux-design/commands/evaluate.md index 45c21b7..36717d0 100644 --- a/research/commands/evaluate.md +++ b/ux-design/commands/evaluate.md @@ -1,5 +1,5 @@ --- -name: research:evaluate +name: ux-design:evaluate description: "Run heuristic evaluation and usability assessment against prototypes" --- # /evaluate diff --git a/research/commands/handoff.md b/ux-design/commands/handoff.md similarity index 89% rename from research/commands/handoff.md rename to ux-design/commands/handoff.md index 6b62283..bcc1747 100644 --- a/research/commands/handoff.md +++ b/ux-design/commands/handoff.md @@ -1,5 +1,5 @@ --- -name: research:handoff +name: ux-design:handoff description: "Synthesize all research into an implementation-ready handoff spec" --- # /handoff diff --git a/research/commands/ingest.md b/ux-design/commands/ingest.md similarity index 90% rename from research/commands/ingest.md rename to ux-design/commands/ingest.md index 33fc51f..94fec41 100644 --- a/research/commands/ingest.md +++ b/ux-design/commands/ingest.md @@ -1,5 +1,5 @@ --- -name: research:ingest +name: ux-design:ingest description: "Frame the problem, identify user groups, and survey the competitive landscape" --- # /ingest diff --git a/research/commands/prototype.md b/ux-design/commands/prototype.md similarity index 88% rename from research/commands/prototype.md rename to ux-design/commands/prototype.md index 9364d26..a33cfc1 100644 --- a/research/commands/prototype.md +++ b/ux-design/commands/prototype.md @@ -1,5 +1,5 @@ --- -name: research:prototype +name: ux-design:prototype description: "Generate design prototypes informed by research findings" --- # /prototype diff --git a/ux-design/commands/publish.md b/ux-design/commands/publish.md new file mode 100644 index 0000000..e33088c --- /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/respond.md b/ux-design/commands/respond.md new file mode 100644 index 0000000..45468bb --- /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 0000000..aee8d5b --- /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/research/guidelines.md b/ux-design/guidelines.md similarity index 89% rename from research/guidelines.md rename to ux-design/guidelines.md index b92034e..328ebce 100644 --- a/research/guidelines.md +++ b/ux-design/guidelines.md @@ -1,4 +1,4 @@ -# Research Workflow Guidelines +# UX Design Workflow Guidelines ## Principles @@ -14,7 +14,10 @@ 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. + 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 @@ -38,7 +41,7 @@ ## Quality - Artifacts should be structured for both human reading and machine - consumption. Use consistent markdown with frontmatter. + 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 diff --git a/research/skills/controller.md b/ux-design/skills/controller.md similarity index 66% rename from research/skills/controller.md rename to ux-design/skills/controller.md index 34075ea..7116abd 100644 --- a/research/skills/controller.md +++ b/ux-design/skills/controller.md @@ -1,11 +1,11 @@ --- name: controller -description: Top-level workflow controller that manages phase transitions for UX research, prototyping, and design handoff. +description: Top-level workflow controller that manages phase transitions for UX design — discovery, prototyping, evaluation, handoff, revision, publication, and review response. --- -# Research Workflow Controller +# UX Design Workflow Controller -You are the workflow controller. Your job is to manage the research workflow +You are the workflow controller. Your job is to manage the ux-design workflow by executing phases and handling transitions between them. ## Phases @@ -14,48 +14,54 @@ by executing phases and handling transitions between them. Frame the problem, identify user groups, and survey the competitive landscape. Produces the discovery artifact. -2. **Investigate** (`/investigate`) — `investigate.md` - Conduct user research — interviews, surveys, analytics, desk research. - Synthesize findings into insights and design recommendations. +2. **Prototype** (`/prototype`) — `prototype.md` + Generate design prototypes informed by discovery and any research the + user brings. Iterative — loops with `/evaluate`. -3. **Prototype** (`/prototype`) — `prototype.md` - Generate design prototypes informed by research findings. Iterative — - loops with `/evaluate`. - -4. **Evaluate** (`/evaluate`) — `evaluate.md` +3. **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` +4. **Handoff** (`/handoff`) — `handoff.md` Synthesize all prior artifacts into an implementation-ready spec with component mapping, interaction specs, and acceptance criteria. +5. **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/research/{issue-key}/` (gitignored). +`.artifacts/ux-design/{issue-key}/` (gitignored). ### Artifact directory -All working artifacts are stored in `.artifacts/research/{issue-key}/` +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` | `/investigate` | -| 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` | +| Prototype files | `02-prototype/` | `/prototype` | +| Prototype notes | `02-prototype/prototype-notes.md` | `/prototype` | +| Evaluation report | `03-evaluation.md` | `/evaluate` | +| Implementation handoff | `04-handoff.md` | `/handoff` | +| PR description | `05-pr-description.md` | `/publish` | +| Publish metadata | `publish-metadata.json` | `/publish` | ## How to Execute a Phase -1. **Announce** the phase to the user: *"Starting /investigate."* +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=`research`, PHASE_FILE=`{phase}.md`. + 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 @@ -73,19 +79,21 @@ happened. ### Typical Flow ```text -ingest → investigate → prototype → evaluate → (iterate? → prototype) or → handoff +ingest → prototype → evaluate → (iterate? → prototype) or → handoff → revise → publish → respond ``` ### What to Recommend **Continuing forward:** -- `/ingest` completed → recommend `/investigate` (almost always the right next step) -- `/investigate` completed → recommend `/prototype` to explore design directions +- `/ingest` 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 → the research workflow is done; recommend the user run `/implement` on the handoff artifact +- `/handoff` completed → recommend `/revise` if the designer 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 **Iteration tracking:** @@ -95,15 +103,13 @@ ingest → investigate → prototype → evaluate → (iterate? → prototype) o **Looping back:** -- `/investigate` reveals the problem framing is wrong → suggest revisiting `/ingest` -- `/prototype` reveals research gaps → suggest additional `/investigate` work +- `/prototype` reveals the problem framing is wrong → suggest revisiting `/ingest` - `/evaluate` reveals fundamental design problems → suggest `/prototype` with specific changes - `/handoff` reveals missing interaction specs → loop back to refine the prototype **Skipping:** -- If the researcher already has research data, they may start at `/prototype` -- If the researcher already has a validated design, they may start at `/handoff` +- If the designer already has a validated design, they may start at `/handoff` - Phase entry requirements are listed below ### Phase Entry @@ -113,10 +119,9 @@ Researchers can enter at any phase if they bring the prerequisite artifact: | Phase | Requires | |-------|----------| | `/ingest` | Jira issue key or feature description | -| `/investigate` | `01-discovery.md` (or equivalent problem framing) | -| `/prototype` | `02-research.md` (or equivalent research findings) | -| `/evaluate` | `03-prototype/` (prototype to evaluate) | -| `/handoff` | `04-evaluation.md` (or researcher confirms design is ready) | +| `/prototype` | `01-discovery.md` (or equivalent problem framing) | +| `/evaluate` | `02-prototype/` (prototype to evaluate) | +| `/handoff` | `03-evaluation.md` (or designer confirms design is ready) | If a prerequisite artifact is missing, tell the researcher which phase produces it and offer to run that phase first. @@ -130,7 +135,6 @@ Recommended next step: /prototype — generate design prototypes based on the approved research findings. Other options: -- /investigate — if you want to gather more research data first - /handoff — if you already have a validated design and want to skip prototyping ``` @@ -157,7 +161,8 @@ If any phase fails (Jira MCP errors, skill unavailability, file errors): or escalate. Do not fabricate results when a tool call fails. Do not silently continue -past errors. +past errors. Recovery must not advance to a later phase — report the error, +re-read this controller, and wait for user direction. ## Context Management @@ -166,7 +171,7 @@ 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/research/{issue-key}/`, and 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 diff --git a/research/skills/evaluate.md b/ux-design/skills/evaluate.md similarity index 95% rename from research/skills/evaluate.md rename to ux-design/skills/evaluate.md index 81fe056..ea49073 100644 --- a/research/skills/evaluate.md +++ b/ux-design/skills/evaluate.md @@ -11,12 +11,11 @@ systematic issues; only humans catch context-dependent problems. ## Prerequisites -Read `.artifacts/research/{issue-key}/03-prototype/prototype-notes.md` +Read `.artifacts/ux-design/{issue-key}/02-prototype/prototype-notes.md` for design decisions and open questions. If the prototype directory doesn't exist, tell the researcher that `/prototype` should run first and stop. -Also read `02-research.md` for user needs that the prototype should address -and `01-discovery.md` for user group context. +Also read `01-discovery.md` for user group context and problem framing. ## Process @@ -32,6 +31,9 @@ Ask the researcher what depth of evaluation is appropriate: 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. @@ -123,7 +125,7 @@ The AI identifies violations; the researcher makes judgment calls. ## Output -`.artifacts/research/{issue-key}/04-evaluation.md` +`.artifacts/ux-design/{issue-key}/03-evaluation.md` ```markdown # Evaluation Report — {issue-key} diff --git a/research/skills/handoff.md b/ux-design/skills/handoff.md similarity index 85% rename from research/skills/handoff.md rename to ux-design/skills/handoff.md index 80b88e4..a5db60c 100644 --- a/research/skills/handoff.md +++ b/ux-design/skills/handoff.md @@ -6,19 +6,19 @@ description: Synthesize research, prototype, and evaluation into an implementati # Handoff — Implementation Spec Synthesize all prior artifacts into a spec that a developer can implement -from. This is the contract between the research workflow and `/implement`. +from. This is the contract between the ux-design workflow and `/implement`. ## Prerequisites -Read all prior artifacts: -- `.artifacts/research/{issue-key}/01-discovery.md` — problem context -- `.artifacts/research/{issue-key}/02-research.md` — user needs and insights -- `.artifacts/research/{issue-key}/03-prototype/prototype-notes.md` — design decisions -- `.artifacts/research/{issue-key}/04-evaluation.md` — evaluation results +Verify these artifacts exist before generating: +- `.artifacts/ux-design/{issue-key}/01-discovery.md` — problem context +- `.artifacts/ux-design/{issue-key}/02-prototype/` — design prototype +- `.artifacts/ux-design/{issue-key}/03-evaluation.md` — evaluation results -If `04-evaluation.md` doesn't exist, ask the researcher: "No evaluation -artifact found. Want to run `/evaluate` first, or proceed with handoff -based on the current prototype?" +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 @@ -71,7 +71,7 @@ not just *what*: ## Output -`.artifacts/research/{issue-key}/05-handoff.md` +`.artifacts/ux-design/{issue-key}/04-handoff.md` ```markdown # Implementation Handoff — {issue-key} @@ -149,9 +149,8 @@ not just *what*: {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` +- **Prototype:** `02-prototype/` +- **Evaluation:** `03-evaluation.md` ### Key Design Decisions diff --git a/research/skills/ingest.md b/ux-design/skills/ingest.md similarity index 91% rename from research/skills/ingest.md rename to ux-design/skills/ingest.md index 65a678f..b6e2487 100644 --- a/research/skills/ingest.md +++ b/ux-design/skills/ingest.md @@ -24,6 +24,10 @@ Extract: 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, competitive search) +or returns zero results: 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? @@ -53,7 +57,7 @@ user research should answer: ## Output -`.artifacts/research/{issue-key}/01-discovery.md` +`.artifacts/ux-design/{issue-key}/01-discovery.md` ```markdown # Discovery — {issue-key} diff --git a/research/skills/prototype.md b/ux-design/skills/prototype.md similarity index 83% rename from research/skills/prototype.md rename to ux-design/skills/prototype.md index d0ab638..6bad4c3 100644 --- a/research/skills/prototype.md +++ b/ux-design/skills/prototype.md @@ -11,13 +11,11 @@ is more valuable than a polished one that can't be changed. ## Prerequisites -Read `.artifacts/research/{issue-key}/02-research.md` for research findings -and design recommendations. If it doesn't exist, tell the researcher that -`/investigate` should run first and stop. +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for problem context, +user groups, and competitive landscape. If it doesn't exist, tell the +designer that `/ingest` should run first and stop. -Also read `01-discovery.md` for problem context and competitive landscape. - -If this is a re-entry from `/evaluate`, read `04-evaluation.md` for the +If this is a re-entry from `/evaluate`, read `03-evaluation.md` for the issues to address in this iteration. ## Process @@ -30,7 +28,7 @@ Determine what input is available for prototyping: |-------------|--------------| | **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 research findings and design recommendations from `/investigate` | +| **Feature description** | Use the discovery brief and any research the designer provides | | **Existing prototype** | Read the current prototype for refinement (iteration from `/evaluate`) | Ask the researcher to confirm the input source and scope before generating. @@ -39,11 +37,11 @@ Ask the researcher to confirm the input source and scope before generating. From the input source, extract or derive user stories: -- Map each research insight to one or more user stories -- Include acceptance criteria derived from research findings -- Prioritize stories by user need priority from `02-research.md` +- 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/research/{issue-key}/03-prototype/user-stories.json`. +Save to `.artifacts/ux-design/{issue-key}/02-prototype/user-stories.json`. ### Step 3: Design Direction (Interactive) @@ -88,6 +86,10 @@ The prototype should cover: 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}/02-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 @@ -100,10 +102,10 @@ finding: ## Output -`.artifacts/research/{issue-key}/03-prototype/` +`.artifacts/ux-design/{issue-key}/02-prototype/` ``` -03-prototype/ +02-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) diff --git a/ux-design/skills/publish.md b/ux-design/skills/publish.md new file mode 100644 index 0000000..75140b8 --- /dev/null +++ b/ux-design/skills/publish.md @@ -0,0 +1,164 @@ +--- +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}/04-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/prd/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. + +### 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 +``` + +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} +``` + +```bash +mkdir -p "{docs_repo_path}/{release}/{feature}" +``` + +```bash +cp ".artifacts/ux-design/{issue-key}/04-handoff.md" "{docs_repo_path}/{release}/{feature}/handoff.md" +``` + +```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}/05-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}/05-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}/05-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/respond.md b/ux-design/skills/respond.md new file mode 100644 index 0000000..809e39d --- /dev/null +++ b/ux-design/skills/respond.md @@ -0,0 +1,121 @@ +--- +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/prd/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}/04-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}/04-handoff.md" "{docs_repo_path}/{handoff_file_path}" +``` + +```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}/04-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 0000000..0afbd9a --- /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}/04-handoff.md` (the deliverable) +- `.artifacts/ux-design/{issue-key}/03-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}/04-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.