diff --git a/AGENTS.md b/AGENTS.md index 875149ce..e99b4166 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ This repository contains reusable AI coding workflows and focused skills that ca - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond) - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff) - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond) +- **ux-design** — UX design workflow (ingest, research, prototype, evaluate, handoff, revise, publish, respond) - **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push) - **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply) - **skill-reviewer** — Meta-workflow that audits AI skill directories @@ -83,7 +84,7 @@ _shared/ review-protocol.md # Shared code review criteria, finding format, severity definitions sizing-rubric.md # Shared sizing definitions (T-shirt sizes, heuristics, team effort guidance) scripts/ - provenance.py # Capture/render CLI (used by prd and design provenance recipes) + provenance.py # Capture/render CLI (used by prd, design, and ux-design provenance recipes) pr-comments.py # Deterministic PR comment operations (fetch, reply, log) publish.py # Deterministic publish operations (push, PR/MR, metadata) resolve-phase.py # Deterministic phase override resolution (file-existence check) @@ -97,7 +98,7 @@ _shared/ validation-gate.md # Pre-commit build/test/lint discovery gate (used by bugfix) ``` -Recipes are self-contained, parameterized procedures that packages reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from a workflow phase). Workflows and simple skills may also reference shared files from guidelines, phases, references, templates, prompts, scripts, and other behavioral files — all such references count as consumers for the shared-file cascade (see Package Versioning). The **prd** and **design** workflows use the provenance recipes on `/draft`, `/revise`, `/respond` (capture) and `/publish` plus docs-sync paths (render). See `_shared/provenance-schema.md` for the published footer format. +Recipes are self-contained, parameterized procedures that packages reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from a workflow phase). Workflows and simple skills may also reference shared files from guidelines, phases, references, templates, prompts, scripts, and other behavioral files — all such references count as consumers for the shared-file cascade (see Package Versioning). The **prd** and **design** workflows use the provenance recipes on `/draft`, `/revise`, `/respond` (capture) and `/publish` plus docs-sync paths (render). The **ux-design** workflow uses them on `/handoff`, `/revise`, `/respond` (capture) and `/publish` plus `/respond` (render). See `_shared/provenance-schema.md` for the published footer format. ### File Reference Conventions @@ -236,7 +237,7 @@ ai-workflows/ │ ├── review-protocol.md # Shared code review criteria and finding format │ ├── sizing-rubric.md # Shared sizing definitions and heuristics │ ├── scripts/ -│ │ ├── provenance.py # Capture/render CLI for prd/design provenance +│ │ ├── provenance.py # Capture/render CLI for prd/design/ux-design provenance │ │ ├── pr-comments.py # Deterministic PR comment operations (fetch, reply, log) │ │ ├── publish.py # Deterministic publish operations (push, PR/MR, metadata) │ │ ├── resolve-phase.py # Deterministic phase override resolution @@ -273,6 +274,7 @@ ai-workflows/ │ ├── references/ │ ├── scripts/ │ └── templates/ +├── ux-design/ ├── install.sh # Installer with auto-discovery ├── uninstall.sh # Removal script ├── AGENTS.md # AI assistant guidance (this file) diff --git a/README.md b/README.md index acec82d5..8280e34f 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,9 @@ Reusable AI coding workflows and focused skills a team member can install global - **Skill Reviewer** -- Meta-workflow that audits AI skill directories against eight quality dimensions. See [skill-reviewer/README.md](skill-reviewer/README.md). +- **UX Design** -- UX design workflow: ingest a feature request, conduct user research, generate prototypes, run heuristic evaluation, and produce a validated design handoff for the `ui-design` workflow. + See [ux-design/README.md](ux-design/README.md). + ## How It Works Each workflow is a top-level directory with a `SKILL.md`, while focused skills diff --git a/_shared/recipes/capture-provenance-event.md b/_shared/recipes/capture-provenance-event.md index 236a6e6f..68ed56c6 100644 --- a/_shared/recipes/capture-provenance-event.md +++ b/_shared/recipes/capture-provenance-event.md @@ -1,6 +1,6 @@ --- name: capture-provenance-event -version: 0.1.1 +version: 0.1.2 --- # Recipe: Capture Provenance Event @@ -11,9 +11,9 @@ phase mutates the planning document. See `../provenance-schema.md`. | Parameter | Required | Description | |-----------|----------|-------------| -| WORKFLOW | Yes | `prd` or `design` | +| WORKFLOW | Yes | `prd`, `design`, or `ux-design` | | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) | -| PHASE | Yes | `draft`, `revise`, or `respond` | +| PHASE | Yes | For `prd` and `design`: `draft`, `revise`, or `respond`. For `ux-design`: `handoff`, `revise`, or `respond` | | AUTHORING_MODE | Yes | `skill` (default for phase skills) or `manual` | ## Procedure diff --git a/_shared/recipes/render-provenance-footer.md b/_shared/recipes/render-provenance-footer.md index 42e4ae73..7851554b 100644 --- a/_shared/recipes/render-provenance-footer.md +++ b/_shared/recipes/render-provenance-footer.md @@ -1,6 +1,6 @@ --- name: render-provenance-footer -version: 0.2.0 +version: 0.2.1 --- # Recipe: Render Provenance Footer @@ -11,7 +11,7 @@ docs-repo copy before `git add`. See `../provenance-schema.md` for format. | Parameter | Required | Description | |-----------|----------|-------------| -| WORKFLOW | Yes | `prd` or `design` | +| WORKFLOW | Yes | `prd`, `design`, or `ux-design` | | ISSUE_KEY | Yes | Full Jira issue key including project prefix (e.g., `PROJ-1234`, not `1234`) | | TARGET_FILE | Yes | Absolute path to the local artifact or docs-repo file to render | | ALLOW_MISSING | No | Set to `yes` only after the user explicitly declines provenance | diff --git a/_shared/scripts/provenance.py b/_shared/scripts/provenance.py index 0a292c85..09c04b4f 100755 --- a/_shared/scripts/provenance.py +++ b/_shared/scripts/provenance.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Capture and render provenance for prd/design planning document workflows. +"""Capture and render provenance for prd/design/ux-design planning documents. Exit codes: 0: Success (capture or render completed) @@ -23,9 +23,29 @@ WORKFLOW_DOCS = { "prd": "03-prd.md", "design": "03-design.md", + "ux-design": "05-handoff.md", } -AUTHORING_PHASES = frozenset({"draft", "revise", "respond", "manual-edit"}) +# The phase that legitimately originates each workflow's document. prd/design +# originate from a template-checked /draft; ux-design assembles its handoff spec +# in /handoff (there is no template-from-origin step), so `handoff` is its +# origin. A first event other than this marks the phase history as untracked. +ORIGIN_PHASE = { + "prd": "draft", + "design": "draft", + "ux-design": "handoff", +} + +AUTHORING_PHASES = frozenset( + {"draft", "handoff", "revise", "respond", "manual-edit"} +) + +# Per-workflow valid phases (for validation in capture_event) +WORKFLOW_PHASES = { + "prd": frozenset({"draft", "revise", "respond", "manual-edit", "commit"}), + "design": frozenset({"draft", "revise", "respond", "manual-edit", "commit"}), + "ux-design": frozenset({"handoff", "revise", "respond", "manual-edit", "commit"}), +} DRIFT_FIELDS = ( "workflow_version", @@ -56,10 +76,18 @@ COMMIT_ONLY_NOTE = ( "> Authoring phases not recorded this session (commit-time snapshot only)." ) -ORIGIN_UNTRACKED_NOTE = ( - "> This document's phase history does not include an initial /draft — " - "structure was not verified against the template from origin." -) +def origin_untracked_note(workflow: str | None = None) -> str: + origin = ORIGIN_PHASE.get(workflow, "draft") + # ux-design has no template step; its /handoff assembles from scratch + if workflow == "ux-design": + return ( + f"> This document's phase history does not include an initial /{origin} — " + "structure was not verified from origin." + ) + return ( + f"> This document's phase history does not include an initial /{origin} — " + "structure was not verified against the template from origin." + ) def repo_root(start: Path) -> Path | None: @@ -260,12 +288,15 @@ def provenance_kind(events: list[dict[str, Any]]) -> str: return "session" -def origin_untracked(events: list[dict[str, Any]]) -> bool: +def origin_untracked( + events: list[dict[str, Any]], workflow: str | None = None +) -> bool: if not events: return False if provenance_kind(events) == "commit_only": return False - return events[0].get("phase") != "draft" + origin = ORIGIN_PHASE.get(workflow, "draft") + return events[0].get("phase") != origin def capture_event( @@ -274,6 +305,14 @@ def capture_event( phase: str, authoring_mode: str, ) -> None: + # Validate phase is valid for this workflow + valid_phases = WORKFLOW_PHASES.get(workflow) + if valid_phases and phase not in valid_phases: + raise ValueError( + f"Phase '{phase}' is not valid for workflow '{workflow}'. " + f"Valid phases: {', '.join(sorted(valid_phases))}" + ) + ai_root = ai_workflows_root() ws_root = workspace_root() path = provenance_path(workflow, issue) @@ -352,6 +391,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]: last = events[-1] if events else {} drift = data.get("drift", {}) kind = provenance_kind(events) + workflow = data.get("workflow", "unknown") return { "schema_version": 1, "provenance_kind": kind, @@ -368,7 +408,7 @@ def build_metrics_payload(data: dict[str, Any]) -> dict[str, Any]: {event.get("authoring_mode", "skill") for event in events} ), "context_changed": drift.get("context_changed", False), - "origin_untracked": origin_untracked(events), + "origin_untracked": origin_untracked(events, workflow), } @@ -403,9 +443,9 @@ def build_footer(data: dict[str, Any]) -> str: if len(phases) > 1: lines.append(f"Phases: {', '.join(phases)}") - if origin_untracked(events): + if origin_untracked(events, workflow): lines.append("") - lines.append(ORIGIN_UNTRACKED_NOTE) + lines.append(origin_untracked_note(workflow)) lines.append("") lines.append(metrics_comment) @@ -491,7 +531,9 @@ def render_footer(workflow: str, issue: str, target: Path, *, allow_missing: boo def main() -> int: - parser = argparse.ArgumentParser(description="PRD/design provenance helper") + parser = argparse.ArgumentParser( + description="PRD/design/ux-design provenance helper" + ) sub = parser.add_subparsers(dest="command", required=True) capture = sub.add_parser("capture", help="Append a provenance event") @@ -500,7 +542,7 @@ def main() -> int: capture.add_argument( "--phase", required=True, - choices=["draft", "revise", "respond", "manual-edit", "commit"], + choices=["draft", "handoff", "revise", "respond", "manual-edit", "commit"], ) capture.add_argument( "--authoring-mode", diff --git a/_shared/scripts/test_provenance.py b/_shared/scripts/test_provenance.py index e405a42b..b547a977 100644 --- a/_shared/scripts/test_provenance.py +++ b/_shared/scripts/test_provenance.py @@ -108,6 +108,46 @@ def test_origin_untracked_false_when_all_events_are_commit(self) -> None: self.assertEqual(provenance.provenance_kind(events), "commit_only") self.assertFalse(provenance.origin_untracked(events)) + def test_origin_untracked_false_for_ux_design_handoff_first(self) -> None: + # ux-design originates its document in /handoff (not /draft), so a + # handoff-first log is a tracked origin and must NOT be flagged. + events = [{"phase": "handoff"}, {"phase": "revise"}] + self.assertFalse(provenance.origin_untracked(events, "ux-design")) + + def test_origin_untracked_true_for_ux_design_revise_first(self) -> None: + # ux-design entered at /revise with no prior /handoff is untracked. + events = [{"phase": "revise"}] + self.assertTrue(provenance.origin_untracked(events, "ux-design")) + + def test_origin_untracked_true_for_prd_handoff_first(self) -> None: + # 'handoff' is not prd's origin phase, so a handoff-first prd log is + # still untracked -- the per-workflow origin must not leak across. + events = [{"phase": "handoff"}] + self.assertTrue(provenance.origin_untracked(events, "prd")) + + def test_origin_untracked_note_names_workflow_origin_phase(self) -> None: + ux_note = provenance.origin_untracked_note("ux-design") + self.assertIn("/handoff", ux_note) + # ux-design has no template step, so note should not mention "template" + self.assertNotIn("template", ux_note) + + prd_note = provenance.origin_untracked_note("prd") + self.assertIn("/draft", prd_note) + self.assertIn("template", prd_note) # prd/design DO have templates + + self.assertIn("/draft", provenance.origin_untracked_note()) + + def test_workflow_phase_validation_rejects_invalid_combinations(self) -> None: + # prd/design don't have 'handoff' phase + with self.assertRaises(ValueError) as cm: + provenance.capture_event("prd", "TEST-123", "handoff", "skill") + self.assertIn("not valid for workflow 'prd'", str(cm.exception)) + + # ux-design doesn't have 'draft' phase + with self.assertRaises(ValueError) as cm: + provenance.capture_event("ux-design", "TEST-456", "draft", "skill") + self.assertIn("not valid for workflow 'ux-design'", str(cm.exception)) + def test_build_metrics_payload_flags_origin_untracked(self) -> None: data = { "workflow": "prd", diff --git a/design/SKILL.md b/design/SKILL.md index dd9e8040..315d649a 100644 --- a/design/SKILL.md +++ b/design/SKILL.md @@ -1,6 +1,6 @@ --- name: design -version: 0.11.3 +version: 0.11.4 description: >- Design-and-decompose workflow that takes a PRD, researches the problem space, drafts a technical design document with a requirement-anchored testplan, diff --git a/install.sh b/install.sh index e2ce1a52..4a3ca94c 100755 --- a/install.sh +++ b/install.sh @@ -160,6 +160,113 @@ ensure_repo_linked() { echo " Linked $INSTALL_DIR -> $REPO_DIR" } +UXD_REPO="https://github.com/rh-uxd/ai-helpers.git" +UXD_DIR="${HOME}/.uxd-ai-skills" +UXD_PLUGINS=(uxd-design uxd-prototype uxd-research) +UXD_REFRESHED=false + +# Install UXD AI Skills via git clone + symlinks (AI-agnostic; works for all +# tools). Called at the end of each install target when ux-design is in scope. +install_uxd_skills() { + local skills_dir="$1" + + # Only install if ux-design is in the workflow set being installed + local has_ux_design=false + for wf in "${PACKAGES[@]}"; do + [[ "$wf" == "ux-design" ]] && has_ux_design=true + done + "$has_ux_design" || return 0 + + if [[ ! -d "$UXD_DIR/.git" ]]; then + if [[ -e "$UXD_DIR" ]]; then + echo " Error: $UXD_DIR exists but is not an ai-helpers Git checkout" >&2 + return 1 + fi + echo " Cloning UXD AI Skills repo (main)..." + git clone --branch main --single-branch "$UXD_REPO" "$UXD_DIR" 2>/dev/null || { + echo " Error: could not clone UXD AI Skills repo — ux-design workflow requires it" >&2 + echo " Check network access to github.com and re-run install." >&2 + return 1 + } + elif [[ "$UXD_REFRESHED" != true ]]; then + local origin_url + local checkout_status + origin_url="$(git -C "$UXD_DIR" remote get-url origin 2>/dev/null)" || { + echo " Error: could not read the UXD AI Skills checkout's origin" >&2 + return 1 + } + if [[ "$origin_url" != "$UXD_REPO" ]]; then + echo " Error: $UXD_DIR has unexpected origin: $origin_url" >&2 + return 1 + fi + + checkout_status="$(git -C "$UXD_DIR" status --short 2>/dev/null)" || { + echo " Error: could not inspect the UXD AI Skills checkout" >&2 + return 1 + } + if [[ -n "$checkout_status" ]]; then + echo " Error: $UXD_DIR has local changes; preserve or remove them before updating" >&2 + return 1 + fi + + echo " Updating UXD AI Skills from main..." + git -C "$UXD_DIR" fetch --quiet origin main 2>/dev/null || { + echo " Error: could not fetch UXD AI Skills main" >&2 + echo " Check network access to github.com and re-run install." >&2 + return 1 + } + + local local_main_sha + local unpushed_commits + local_main_sha="$(git -C "$UXD_DIR" rev-parse --verify refs/heads/main 2>/dev/null)" || local_main_sha="" + if [[ -n "$local_main_sha" ]]; then + unpushed_commits="$(git -C "$UXD_DIR" rev-list --count origin/main..refs/heads/main 2>/dev/null)" || { + echo " Error: could not compare local main with origin/main" >&2 + return 1 + } + if [[ "$unpushed_commits" -gt 0 ]]; then + echo " Error: local main has $unpushed_commits commit(s) not in origin/main; preserve them before updating." >&2 + echo " Create a backup branch or push the commits, then re-run install." >&2 + return 1 + fi + fi + + git -C "$UXD_DIR" checkout --quiet -B main origin/main 2>/dev/null || { + echo " Error: could not check out the latest UXD AI Skills main" >&2 + return 1 + } + fi + UXD_REFRESHED=true + echo " UXD AI Skills main: $(git -C "$UXD_DIR" rev-parse --short HEAD)" + + local linked_count=0 + for plugin in "${UXD_PLUGINS[@]}"; do + local plugin_skills="${UXD_DIR}/plugins/${plugin}/skills" + if [[ ! -d "$plugin_skills" ]]; then + echo " Error: expected UXD skills directory is missing: ${plugin_skills}" >&2 + return 1 + fi + for skill_dir in "${plugin_skills}"/*/; do + [[ -d "$skill_dir" ]] || continue + local skill_name + skill_name="$(basename "$skill_dir")" + local target="${skills_dir}/${skill_name}" + if [[ -e "$target" && ! -L "$target" ]]; then + echo " Warning: ${target} exists and is not a symlink; skipping" >&2 + continue + fi + ln -sfn "$skill_dir" "$target" + echo " Linked ${target} -> ${skill_dir} (uxd)" + ((linked_count += 1)) + done + done + + if (( linked_count == 0 )); then + echo " Error: no UXD skills were found in the expected plugin directories" >&2 + return 1 + fi +} + install_shared() { local target_dir="$1" if [[ ! -d "${INSTALL_DIR}/_shared" ]]; then @@ -236,6 +343,7 @@ install_cursor() { echo " Linked ${SKILLS_DIR}/${package} -> ${package_dir} ($SCOPE)" done generate_cursor_commands "$CMDS_DIR" + install_uxd_skills "$SKILLS_DIR" } install_claude() { @@ -324,6 +432,7 @@ install_claude() { echo " Removed stale commands symlink ${CMDS_DIR}/${package} ($SCOPE)" fi done + install_uxd_skills "$SKILLS_DIR" } install_gemini() { @@ -341,6 +450,7 @@ install_gemini() { ln -sfn "$package_dir" "${SKILLS_DIR}/${package}" echo " Linked ${SKILLS_DIR}/${package} -> ${package_dir} ($SCOPE)" done + install_uxd_skills "$SKILLS_DIR" } install_codex() { @@ -358,6 +468,7 @@ install_codex() { ln -sfn "$package_dir" "${SKILLS_DIR}/${package}" echo " Linked ${SKILLS_DIR}/${package} -> ${package_dir} ($SCOPE)" done + install_uxd_skills "$SKILLS_DIR" } # Offer a daily systemd --user notifier (Linux desktop). Default: no. diff --git a/prd/SKILL.md b/prd/SKILL.md index 75c8587b..396a7835 100644 --- a/prd/SKILL.md +++ b/prd/SKILL.md @@ -1,6 +1,6 @@ --- name: prd -version: 0.11.3 +version: 0.11.4 description: >- Requirements-to-PRD workflow that ingests requirements from Jira, clarifies ambiguities through iterative Q&A, drafts a Product Requirements Document, diff --git a/skills/report-bug/SKILL.md b/skills/report-bug/SKILL.md index 29af0ab9..12467cfd 100644 --- a/skills/report-bug/SKILL.md +++ b/skills/report-bug/SKILL.md @@ -1,6 +1,6 @@ --- name: report-bug -version: 0.1.0 +version: 0.1.1 description: >- Draft and submit a well-specified Jira bug report after explicit confirmation. Use when a user wants to report, file, log, or open a bug rather than fix it now. diff --git a/skills/report-bug/scripts/test_render_issue.py b/skills/report-bug/scripts/test_render_issue.py index ef1de9bc..941d6810 100644 --- a/skills/report-bug/scripts/test_render_issue.py +++ b/skills/report-bug/scripts/test_render_issue.py @@ -192,7 +192,7 @@ def test_provenance_uses_skill_and_authoritative_assistant_identity(self): provenance = render_issue.build_provenance(self.model(), skill) self.assertEqual( provenance, - "Reported with AI assistance using report-bug v0.1.0. Review for accuracy.", + "Reported with AI assistance using report-bug v0.1.1. Review for accuracy.", ) raw = self.raw_model() @@ -265,7 +265,7 @@ def test_cli_emits_parseable_adf(self): self.assertEqual(result.stderr, "") adf = json.loads(result.stdout) self.assertEqual(adf["type"], "doc") - self.assertIn("report-bug v0.1.0", adf["content"][-1]["content"][0]["text"]) + self.assertIn("report-bug v0.1.1", adf["content"][-1]["content"][0]["text"]) def test_cli_emits_markdown_preview(self): result = self.run_cli( @@ -274,7 +274,7 @@ def test_cli_emits_markdown_preview(self): ) self.assertEqual(result.returncode, 0, result.stderr) self.assertTrue(result.stdout.startswith("## Description of the problem\n")) - self.assertIn("report-bug v0.1.0", result.stdout) + self.assertIn("report-bug v0.1.1", result.stdout) def test_cli_can_disable_provenance_by_policy(self): result = self.run_cli( diff --git a/ux-design/README.md b/ux-design/README.md new file mode 100644 index 00000000..e89707d1 --- /dev/null +++ b/ux-design/README.md @@ -0,0 +1,248 @@ +# UX Design Workflow + +A UX design workflow that supports early research and exploratory prototypes +from a Jira Feature or a published PRD path, then enriches that context from +the design document and linked `[UX]` story. Feature-only and PRD-only work can +iterate through research, prototyping, and evaluation. It cannot produce the +implementation handoff consumed by `ui-design` until all required inputs and +the active design have been reviewed. + +## Phase Flow + +```mermaid +graph TD + early_ingest([Feature-only or PRD-only ingest]) --> research + early_ingest --> prototype + research --> prototype + prototype --> evaluate + evaluate -->|iterate| prototype + prototype -->|research gap| research + early_ingest -->|design and UX story available| enrich([Enrich same Feature context]) + enrich --> research + enrich --> prototype + enrich --> evaluate + evaluate -->|current context and prototype| handoff + handoff --> revise + handoff --> publish + revise --> publish + publish --> respond +``` + +Research is conditional — skip directly to `/prototype` if the researcher +already has validated data or well-understood user needs. Feature-only and +PRD-only work is exploratory; re-ingest when the design document and linked +`[UX]` story are available. Reconcile prior work and evaluate the active +prototype against the enriched context before handoff. + +## Prerequisites + +| Tool | Required | Purpose | +|------|----------|---------| +| Jira access (MCP or CLI) | For Jira-backed `/ingest` | Fetch a Feature or `[UX]` story; direct PRD-path ingestion does not fetch Jira content | +| Published PRD (`prd.md`) | For PRD-path `/ingest` or later context enrichment | Load product requirements before the design document exists | +| Published design doc (`design.md`) | For handoff context enrichment | Load technical constraints and data/API context | +| UXD Research, Prototype, and Design plugins | Required | Discovery, prototyping, evaluation, and handoff skills | +| Jira access (Atlassian MCP) | For Full `/evaluate` | `uxd-prototype-evaluate` fetches story acceptance criteria | +| `python3`, Node/npm, and Playwright Chromium | For Full `/evaluate` | Prototype evaluation helper scripts and browser walkthroughs | + +`/ingest` loads upstream inputs from **shared** locations (Jira and the +published docs repo or an explicitly supplied published PRD path) — never from +another workflow's private `.artifacts/`. Missing documents are recorded as +gaps during exploratory work. `/handoff` requires the PRD, design document, +and linked `[UX]` story to be ingested. + +## Phases + +| Phase | Command | Purpose | Artifact(s) | +|-------|---------|---------|-------------| +| Ingest | `/ingest` | Start from a Feature or published PRD path, or enrich its context from a linked story and design document | `00-context.md`, `01-discovery.md` | +| Research | `/research` | Conduct user research, synthesize findings | `02-research.md` | +| Prototype | `/prototype` | Generate design prototypes from research | `03-prototype/` | +| Evaluate | `/evaluate` | Heuristic evaluation and usability assessment | `04-evaluation.md` | +| Design handoff | `/handoff` | Produce an implementation-ready spec after enriched context and current prototype evaluation | `05-handoff.md` | +| Revise | `/revise` | Incorporate stakeholder feedback | `05-handoff.md` (updated) | +| Publish | `/publish` | Push handoff spec to docs repo for review | `06-pr-description.md`, `publish-metadata.json`, PR in docs repo | +| Respond | `/respond` | Address PR reviewer comments | Updated `05-handoff.md` | + +## Typical Flow + +```text +/ingest EDM-Feature + → loads the Feature issue without requiring a PRD or design document + → frames the problem, identifies user groups, and records assumptions + → writes exploratory context under .artifacts/ux-design/EDM-Feature/ + +Alternative when the PRD exists before the design document: +/ingest "path/to/published/feature-directory/prd.md" + → uses the Feature key found in PRD metadata or the parent directory + (or asks for the Feature key to use as the stable context key) + → reads only that PRD; records design and UX story as not ingested + → writes an exploratory discovery brief under the same Feature-scoped path + +/research (conditional — skip if you have data) + → conducts user research + → synthesizes findings into themed insights + → documents persona-specific needs + → records the discovery revision that framed the work + +/prototype + → creates an exploratory prototype informed by research + → records the discovery revision and prototype iteration + +/evaluate + → evaluates the active prototype against its discovery revision + → writes 04-evaluation.md + → loops to /prototype or /research as findings require + +/ingest EDM-UX + → resolves the linked Feature key and reuses its existing artifact directory + → loads the design document, story references, and sibling stories + (and the PRD if it was not already ingested) + → preserves the prior context and assesses which research/prototype findings + remain applicable + → updates 01-discovery.md with the enriched context revision + +/research, /prototype, /evaluate + → reconcile earlier evidence and design decisions with the enriched context + → preserve earlier research, prototypes, and evaluations in history + +/handoff + → proceeds only when PRD, design document, and linked [UX] story are ingested + and the active prototype and evaluation match the current context revision + → synthesizes current artifacts into implementation spec + → maps UI elements to design system components + → annotates data requirements per UI element + → documents persona-specific views + → reality-checks the design against the technical design (final vision + vs. MVP/phase-1 split when constraints require it) + → writes 05-handoff.md + +/publish + → pushes 05-handoff.md to docs repo + → opens PR for team review + +/respond + → addresses PR review comments + → updates 05-handoff.md as needed +``` + +## Artifacts + +All artifacts are stored in `.artifacts/ux-design/{context-key}/`. For a +Jira-backed context, the Feature key is the stable context key, including when +later phases are invoked with the linked `[UX]` story. For a description-only +context, use the stable key agreed during `/ingest` (for example, +`description-`). + +```text +.artifacts/ux-design/EDM-1234/ + 00-context.md (Feature/story links, revision, maturity, active bases) + 01-discovery.md (current problem framing and upstream context) + 02-research.md (research findings, insights, recommendations) + 03-prototype/ (mirrored skill output + design rationale) + prototype-notes.md (design decisions, user stories covered) + prototype/ (generated prototype files, from the skill) + 04-evaluation.md (heuristic eval report, readiness assessment) + 04-eval-raw/ (raw skill reports, mirrored from the eval skills) + history/ (prior context snapshots, prototypes, evaluations) + 05-handoff.md (implementation spec, component mapping, AC) + 06-pr-description.md (generated PR body for /publish) + publish-metadata.json (PR tracking: number, URL, branch, head SHA) + provenance.json (authoring provenance log) +``` + +## Contract for the handoff + +`05-handoff.md` is the primary artifact consumed by the `ui-design` workflow. +It can be created only after `00-context.md` is `enriched`, `01-discovery.md` +contains the PRD and design document, and the linked `[UX]` story is recorded. +Its prototype must be reviewed against that discovery revision, and its +evaluation must cover the same revision and prototype iteration. Feature-only +or PRD-only research and prototypes remain useful inputs; they are never +sufficient on their own for this contract. + +It contains: + +- **Component mapping** — UI elements mapped to design system components +- **Interaction specs** — every user interaction documented +- **State enumeration** — empty, loading, error, populated, responsive +- **Data annotations** — what data each UI element needs (with gaps flagged) +- **Persona-specific views** — where user groups interact differently +- **Acceptance criteria** — testable, traced to research findings +- **Feasibility and phasing** — design reality-checked against the technical + design, with a final-vision/MVP split when constraints require it +- **Research context** — why decisions were made + +## UXD Marketplace Skills + +This workflow uses skills from the +[UXD AI Skills repository](https://github.com/rh-uxd/ai-helpers). The installer +clones its current `main` branch and refreshes an existing clean checkout on +each run of `./install.sh`; it does not pin a commit. The upstream team will +notify us before breaking changes. + +The installer links skill folders by bare name for Claude Code, Cursor, Gemini, +and Codex. Invoke the skill name directly rather than using a plugin-marketplace +namespace. + +| Skill | Upstream plugin | Used by | +|-------|-----------------|---------| +| `uxd-discovery` | `uxd-research` | `/ingest` | +| `uxd-prototype-create` | `uxd-prototype` | `/prototype` | +| `uxd-prototype-export` | `uxd-prototype` | Optional export from prototype creation | +| `uxd-prototype-evaluate` | `uxd-prototype` | `/evaluate` (Full) | +| `uxd-prototype-publish` | `uxd-prototype` | Optional standalone publishing | +| `uxd-research-heuristic-eval` | `uxd-research` | `/evaluate` | +| `uxd-evaluate-design-heuristics` | `uxd-research` | `/evaluate` | +| `uxd-design-handoff` | `uxd-design` | `/handoff` | +| `uxd-figma-read` | `uxd-design` | Optional standalone use; prototype creation reads Figma links directly | + +**Runtime paths:** Some upstream skills use `CLAUDE_SKILL_DIR` and +`CLAUDE_PLUGIN_ROOT` to locate scripts or plugin resources. Claude Code supplies +these variables. In other runtimes, resolve a skill under +`${HOME}/.uxd-ai-skills/plugins//skills/` and its plugin root at +`${HOME}/.uxd-ai-skills/plugins/`. Supply the expected path to helpers +when needed. Full evaluation also requires Atlassian MCP access, Node/npm, and +Playwright Chromium; if those prerequisites are unavailable, do not silently +skip or downgrade the requested Full evaluation. + +## Directory Structure + +```text +ux-design/ +├── SKILL.md # Workflow entry point +├── guidelines.md # Behavioral rules and guardrails +├── README.md # This file +├── skills/ +│ ├── controller.md # Phase dispatcher and transitions +│ ├── ingest.md # Frame problem, identify user groups +│ ├── research.md # Conduct user research +│ ├── prototype.md # Generate design prototypes +│ ├── evaluate.md # Heuristic evaluation +│ ├── handoff.md # Design-to-implementation spec +│ ├── revise.md # Incorporate stakeholder feedback +│ ├── publish.md # Push to docs repo PR +│ └── respond.md # Address PR review comments +└── commands/ + ├── ingest.md # /ingest command + ├── research.md # /research command + ├── prototype.md # /prototype command + ├── evaluate.md # /evaluate command + ├── handoff.md # /handoff command + ├── revise.md # /revise command + ├── publish.md # /publish command + └── respond.md # /respond command +``` + +## Getting Started + +```bash +# Install the workflow +./install.sh claude --workflows ux-design + +# Or install all workflows +./install.sh all +``` + +Then in your project, run `/ingest` with a Jira issue key or feature +description to begin. diff --git a/ux-design/SKILL.md b/ux-design/SKILL.md new file mode 100644 index 00000000..90c1685f --- /dev/null +++ b/ux-design/SKILL.md @@ -0,0 +1,28 @@ +--- +name: ux-design +version: 0.1.0 +description: >- + UX design workflow that supports early research and exploratory prototyping + from a Jira Feature or published PRD, then enriches the same context from its + design document and linked [UX] story before implementation handoff. Contexts + missing any of those upstream inputs remain exploratory and cannot be handed + off to ui-design. + Activated by commands: /ingest, /research, /prototype, /evaluate, /handoff, /revise, /publish, /respond. +--- +# UX Design Workflow Orchestrator + +## Quick Start + +1. If the user invoked a command, read its wrapper: + [ingest](commands/ingest.md), [research](commands/research.md), [prototype](commands/prototype.md), + [evaluate](commands/evaluate.md), [handoff](commands/handoff.md), [revise](commands/revise.md), + [publish](commands/publish.md), or [respond](commands/respond.md). +2. Otherwise, read `skills/controller.md` to load the workflow controller: + - If the user provided a Jira issue key or URL, execute the `/ingest` phase + - Otherwise, execute the first phase the user requests + +If a step fails or produces unexpected output, stop and report the error to +the user. Do not advance to the next phase. Offer to retry the failed step or +escalate. + +For principles, hard limits, and escalation rules, see `guidelines.md`. diff --git a/ux-design/commands/evaluate.md b/ux-design/commands/evaluate.md new file mode 100644 index 00000000..36717d0f --- /dev/null +++ b/ux-design/commands/evaluate.md @@ -0,0 +1,11 @@ +--- +name: ux-design:evaluate +description: "Run heuristic evaluation and usability assessment against prototypes" +--- +# /evaluate + +Read `../skills/controller.md` and follow it. + +Dispatch the **evaluate** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/handoff.md b/ux-design/commands/handoff.md new file mode 100644 index 00000000..bcc1747d --- /dev/null +++ b/ux-design/commands/handoff.md @@ -0,0 +1,11 @@ +--- +name: ux-design:handoff +description: "Synthesize all research into an implementation-ready handoff spec" +--- +# /handoff + +Read `../skills/controller.md` and follow it. + +Dispatch the **handoff** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/ingest.md b/ux-design/commands/ingest.md new file mode 100644 index 00000000..721f3ba9 --- /dev/null +++ b/ux-design/commands/ingest.md @@ -0,0 +1,11 @@ +--- +name: ux-design:ingest +description: "Ingest a Jira Feature, published PRD path, UX story, or feature description" +--- +# /ingest + +Read `../skills/controller.md` and follow it. + +Dispatch the **ingest** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/prototype.md b/ux-design/commands/prototype.md new file mode 100644 index 00000000..a33cfc1b --- /dev/null +++ b/ux-design/commands/prototype.md @@ -0,0 +1,11 @@ +--- +name: ux-design:prototype +description: "Generate design prototypes informed by research findings" +--- +# /prototype + +Read `../skills/controller.md` and follow it. + +Dispatch the **prototype** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/publish.md b/ux-design/commands/publish.md new file mode 100644 index 00000000..e33088cb --- /dev/null +++ b/ux-design/commands/publish.md @@ -0,0 +1,11 @@ +--- +name: ux-design:publish +description: "Push the handoff spec as a GitHub PR for external review" +--- +# /publish + +Read `../skills/controller.md` and follow it. + +Dispatch the **publish** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/research.md b/ux-design/commands/research.md new file mode 100644 index 00000000..277d60d8 --- /dev/null +++ b/ux-design/commands/research.md @@ -0,0 +1,11 @@ +--- +name: ux-design:research +description: "Conduct user research, gather data, and synthesize findings into insights" +--- +# /research + +Read `../skills/controller.md` and follow it. + +Dispatch the **research** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/respond.md b/ux-design/commands/respond.md new file mode 100644 index 00000000..45468bbf --- /dev/null +++ b/ux-design/commands/respond.md @@ -0,0 +1,11 @@ +--- +name: ux-design:respond +description: "Fetch and address reviewer comments on the handoff spec PR" +--- +# /respond + +Read `../skills/controller.md` and follow it. + +Dispatch the **respond** phase. Context: + +$ARGUMENTS diff --git a/ux-design/commands/revise.md b/ux-design/commands/revise.md new file mode 100644 index 00000000..aee8d5b0 --- /dev/null +++ b/ux-design/commands/revise.md @@ -0,0 +1,11 @@ +--- +name: ux-design:revise +description: "Incorporate stakeholder feedback into the handoff spec" +--- +# /revise + +Read `../skills/controller.md` and follow it. + +Dispatch the **revise** phase. Context: + +$ARGUMENTS diff --git a/ux-design/guidelines.md b/ux-design/guidelines.md new file mode 100644 index 00000000..02773c72 --- /dev/null +++ b/ux-design/guidelines.md @@ -0,0 +1,130 @@ +# UX Design Workflow Guidelines + +## Principles + +- The handoff spec represents the **team's** agreed UX approach, not the AI's + interpretation. Always confirm before finalizing content. +- Trace every design decision back to a research finding or user direction. + Do not invent user needs or fabricate evidence. +- **Evidence over assumption.** When research data is unavailable, say so + explicitly. "We don't have data on this" is valuable — silence is not. +- **Precision over verbosity.** A concise, well-structured handoff gets better + reviews. Cover everything that matters; don't pad it. +- Preserve the researcher's terminology and domain language. Do not rewrite + their findings into generic UX jargon. +- Prototypes are conversation starters, not final designs. A rough prototype + the researcher can react to is more valuable than a polished one they can't. +- Heuristic evaluation supplements — never replaces — real user testing. + AI-driven evaluation catches systematic issues; only humans catch context- + dependent usability problems. The handoff spec must note the evaluation + method and flag when real user testing has not been conducted. +- **Research is conditional.** Not every feature needs a dedicated research + phase. `/research` is recommended when user needs are unclear or unvalidated. + Skip to `/prototype` if the researcher already has validated data. +- **Incomplete context is exploratory.** Research and prototypes based only on + a Jira Feature or PRD can inform later planning, but cannot be handed off to + `ui-design`. + +## 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 must be anonymized before + inclusion. Use role-based labels ("User P1", "Admin P2"), not names. +- No publishing artifacts without explicit researcher approval. +- No skipping the human gate between phases. Present findings, get confirmation. +- `/handoff` requires an enriched context with the published PRD, design + document, and linked `[UX]` story, plus a prototype and evaluation reviewed + against the current context revision. Do not create a partial handoff from a + Feature-only or PRD-only context. +- No committing to `main` directly. Use feature branches for `/publish`. +- **No personal names in generated content.** Replace references to individuals + from Jira tickets, interview notes, or other source material with role-based + descriptions ("the fleet admin reported…", "a participant noted…"). Author + metadata fields are exempt — they identify the document author, not + referenced individuals. +- **No scope reduction.** Never silently defer design decisions to "v2" or + mark states as "future enhancement" to reduce scope. If scope won't fit + a single research cycle, propose a split — don't quietly drop it. + +## Safety + +- Show your work before finalizing. After each phase, present artifacts for + review — do not assume they are ready. +- Flag assumptions explicitly. If research data doesn't cover something and + you filled it in, mark it clearly as an assumption. +- Indicate confidence levels on recommendations. Distinguish between findings + backed by multiple data sources (HIGH) and single-source observations (LOW). +- Before `/publish`, confirm the target repository, branch, and PR details + with the researcher. + +## Quality + +- Artifacts must be structured for both human reading and machine consumption. + Use consistent markdown headings and table formats — downstream workflows + (ui-design, ui-implement) parse these artifacts programmatically. +- The handoff spec must be detailed enough for a developer to implement without + additional design consultation. If a developer would need to ask a question, + the answer belongs in the spec. +- Heuristic evaluation findings must include severity ratings and specific + remediation guidance — not just observations. +- Acceptance criteria must be **behavioral outcomes** (what the system does, + testable from outside), not activities or implementation details. +- The Data Annotations and Persona-Specific Views sections of the handoff spec + are required, not optional. If all user groups interact identically, say so + explicitly. If no UI element has data uncertainty, say so explicitly. Do not + omit these sections. + +## Escalation + +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 +- Confidence in a design recommendation is low + +## Artifact Persistence and Isolation + +- All workflow artifacts MUST be stored under `.artifacts/ux-design/{issue-key}/`, + where `{issue-key}` is the stable Feature key for a Jira-backed context. +- Keep the Feature key as the artifact key when the workflow later receives a + linked `[UX]` story. Record story keys separately in `00-context.md`. +- Preserve prior context and phase artifacts under `history/` before replacing + them. Never overwrite history snapshots. Record which context revision each + research synthesis, prototype iteration, and evaluation used. +- NEVER read from another workflow's `.artifacts/` directory (`.artifacts/prd/`, + `.artifacts/design/`, etc.) — those are private working directories, not + interfaces +- Shared inputs MUST come from published locations: + - Jira issues (read-only) + - Published docs repository (PRD, design doc, clarifications) + - `.artifacts/config.json` (shared repo configuration) + - Project files (AGENTS.md, CLAUDE.md, design system docs) +- When a downstream workflow needs this workflow's output, it reads from the + published docs repository (via `/publish`), not from `.artifacts/ux-design/` + +## Shell Command Safety + +When instructing the AI to interpolate values into shell commands (e.g., Jira +titles, branch names, user input): + +- Always quote interpolated values with double quotes +- Never pass unvalidated free-form text (e.g., Jira issue summaries) as + command-line flags unquoted +- Validate values match expected patterns before interpolation when possible + +Example: `git commit -m "${title}"` not `git commit -m $title` + +## 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 +- Use the configured docs repository for `/publish` operations diff --git a/ux-design/skills/controller.md b/ux-design/skills/controller.md new file mode 100644 index 00000000..8d473d70 --- /dev/null +++ b/ux-design/skills/controller.md @@ -0,0 +1,268 @@ +--- +name: controller +description: Top-level workflow controller that manages phase transitions for UX design — discovery, user research, prototyping, evaluation, handoff, revision, publication, and review response. +--- + +# UX Design Workflow Controller + +You are the workflow controller. Your job is to manage the ux-design workflow +by executing phases and handling transitions between them. + +## Phases + +1. **Ingest** (`/ingest`) — [ingest.md](ingest.md) + Accept a Jira Feature, published PRD path, or `[UX]` story. Feature-only or + PRD-only input can start exploratory research and prototyping. When the + design document and linked story become available, enrich the same + Feature-scoped context and assess which prior artifacts still apply. + +2. **Research** (`/research`) — [research.md](research.md) + Conduct user research — interviews, surveys, analytics, desk research. + Synthesize findings into insights and design recommendations. Conditional: + recommended when user needs are unclear or unvalidated; skippable if the + researcher already has validated research data. + +3. **Prototype** (`/prototype`) — [prototype.md](prototype.md) + Generate design prototypes informed by discovery and research findings. + Iterative — loops with `/evaluate`. + +4. **Evaluate** (`/evaluate`) — [evaluate.md](evaluate.md) + Run heuristic evaluation and usability assessment against prototypes. + Iterative — loops back to `/prototype` or advances to `/handoff`. + +5. **Design handoff** (`/handoff`) — [handoff.md](handoff.md) + Synthesize all prior artifacts into an implementation-ready spec with + component mapping, interaction specs, data annotations, persona-specific + views, and acceptance criteria — reality-checked against the technical + design, with a final-vision/MVP split when constraints require it. + +6. **Revise** (`/revise`) — [revise.md](revise.md) + Incorporate stakeholder feedback into the handoff spec. Repeatable. + +7. **Publish** (`/publish`) — [publish.md](publish.md) + Push the handoff spec as a PR to the docs repo for external review. + +8. **Respond** (`/respond`) — [respond.md](respond.md) + Fetch and address PR reviewer comments on the published handoff spec. + +## Workspace + +All work happens in the **source repo** — the researcher needs codebase +context to make informed design decisions. Planning artifacts live in +`.artifacts/ux-design/{issue-key}/` (gitignored), where `{issue-key}` is the +Feature key for a Jira-backed context or PRD path. For a PRD without a Feature +key in its metadata or directory, ask the researcher for the Feature key to +use as the stable context key. A linked `[UX]` story key is recorded +separately and used for story-specific operations such as Full evaluation. + +### Artifact directory + +All working artifacts are stored in `.artifacts/ux-design/{issue-key}/` +within the source repo: + +| Artifact | File | Written by | +|----------|------|------------| +| Context manifest | `00-context.md` | `/ingest` and downstream phases | +| Discovery brief | `01-discovery.md` | `/ingest` | +| Research findings | `02-research.md` | `/research` | +| Prototype files | `03-prototype/` | `/prototype` | +| Prototype notes | `03-prototype/prototype-notes.md` | `/prototype` | +| Evaluation report | `04-evaluation.md` | `/evaluate` | +| Implementation handoff | `05-handoff.md` | `/handoff` | +| Provenance log | `provenance.json` | `/handoff`, `/revise`, `/respond` | +| PR description | `06-pr-description.md` | `/publish` | +| Publish metadata | `publish-metadata.json` | `/publish` | + +When context is enriched, `/ingest` preserves the prior active artifacts in +`history/context-r{N}/`. Never overwrite history snapshots. Prototype +iterations and evaluation reports also record the discovery revision they +use, so old evaluations cannot qualify a newer design for handoff. + +## How to Execute a Phase + +1. **Announce** the phase to the user: *"Starting /prototype."* +2. **Locate** the skill file — read and follow + `../../_shared/recipes/phase-override-resolution.md` with + WORKFLOW=`ux-design`, PHASE_FILE=`{phase}.md`. +3. **Read** the resolved skill file +4. **Execute** the skill's steps — the user should see your progress +5. When the skill is done, it will tell you to report findings and + re-read this controller. Do that — then use "Recommending Next Steps" + below to offer options. +6. Present the skill's results and your recommendations to the user +7. **Stop and wait** for the user to tell you what to do next. + +## Recommending Next Steps + +After each phase completes, present the user with **options** — not just one +next step. Use the typical flow as a baseline, but adapt to what actually +happened. + +### Typical Flows + +```text +Feature-only: +/ingest Feature → [research] → prototype ⇄ evaluate + ↖ additional research when needed + +PRD-only: +/ingest path/to/published/prd.md → [research] → prototype ⇄ evaluate + → remains exploratory until the design document and linked [UX] story are ingested + +Enriched: +/ingest [UX] story → reconcile prior work → [research] → prototype ⇄ evaluate → handoff → revise → publish → respond +``` + +Research is conditional in either flow. Feature-only and PRD-only prototypes +and evaluations are exploratory. `/handoff` is available only after context is +enriched with the PRD, design document, and linked `[UX]` story, and the active +prototype and evaluation have been reviewed against that context. + +### What to Recommend + +**Continuing forward:** + +- Initial Feature-only or PRD-only `/ingest` completed → recommend `/research` + if user needs are unclear or unvalidated; otherwise recommend `/prototype`. + Keep the work exploratory until the context is enriched. +- Enrichment `/ingest` completed → present the context-change assessment. + Recommend `/research` for new or affected questions, `/prototype` to review + or revise the active design, and `/evaluate` again before handoff. +- `/research` completed → recommend `/prototype` to explore design directions +- `/prototype` completed → recommend `/evaluate` (always — never skip evaluation) +- `/evaluate` completed (no critical issues, enriched context, current prototype) → recommend `/handoff` +- `/evaluate` completed on exploratory context → keep work exploratory; recommend enrichment when the design document and linked `[UX]` story are available +- `/evaluate` completed (critical issues) → recommend `/prototype` to iterate +- `/handoff` completed → recommend `/revise` if the researcher wants + stakeholder feedback, or `/publish` to push the spec to the docs repo +- `/revise` completed → recommend `/publish` (or another `/revise` round) +- `/publish` completed → recommend sharing the PR with reviewers, then + `/respond` when comments arrive +- `/respond` completed → recommend another `/respond` round if new comments + arrive, or the workflow is done + +**When to recommend `/research`:** + +After `/ingest` completes, recommend `/research` when: +- The discovery brief surfaces significant unknowns about user needs +- The researcher doesn't have existing interviews, surveys, or analytics +- Competing design directions exist and research would break the tie +- The strategic decisions in the discovery brief require user data to resolve + +When the researcher already has validated research data or well-understood +user needs, recommend `/prototype` directly. + +**Iteration tracking:** + +- Track the number of prototype→evaluate cycles +- After 3 cycles with enriched context, explicitly ask: "We've iterated 3 times. Ready for handoff, or continue refining?" With exploratory context, ask whether the design document and linked `[UX]` story are available yet; keep the design exploratory until they are. +- The researcher decides — no hard cap + +**Looping back:** + +- `/research` reveals the problem framing is wrong → suggest revisiting `/ingest` +- `/prototype` reveals research gaps → suggest additional `/research` work +- `/evaluate` reveals fundamental design problems → suggest `/prototype` with specific changes +- Enrichment `/ingest` changes the current context revision → review earlier + research and prototype decisions; an evaluation from an older revision does + not satisfy the handoff gate +- `/handoff` reveals missing interaction specs → loop back to refine the prototype + +**Skipping:** + +- `/research` is always skippable — go directly to `/prototype` if the + researcher has sufficient domain knowledge or existing research data +- If the researcher already has a validated design, they may start at `/handoff` only when the enriched context and current evaluation prerequisites are present +- Phase entry requirements are listed below + +### Phase Entry + +Researchers can enter at any phase if they bring the prerequisite artifact: + +| Phase | Requires | +|-------|----------| +| `/ingest` | Jira Feature key, `[UX]` story key, published `prd.md` path, or feature description | +| `/research` | `01-discovery.md` (or equivalent problem framing) | +| `/prototype` | `01-discovery.md` or equivalent problem framing; `02-research.md` when `/research` runs, otherwise researcher confirms sufficient domain knowledge or validated research data | +| `/evaluate` | Active prototype reviewed against current discovery. Full additionally needs the linked `[UX]` story key, Jira/browser access, and the private evaluator run root described in `evaluate.md` | +| `/handoff` | Enriched `00-context.md` (PRD, design document, linked `[UX]` story), current discovery, active prototype reviewed against it, and an evaluation of that prototype against the same context revision | +| `/revise` | `05-handoff.md` | +| `/publish` | `05-handoff.md` | +| `/respond` | `publish-metadata.json` (PR must exist) | + +If a prerequisite artifact is missing, tell the researcher which phase +produces it and offer to run that phase first. For `/handoff`, do not offer a +partial-handoff override when the context is still exploratory or the active +prototype/evaluation has not been reconciled with the current revision. + +### How to Present Options + +Lead with your top recommendation, then list alternatives briefly: + +```text +Recommended next step: /prototype — generate design prototypes based on +the approved research findings. + +Other options: +- /handoff — if the PRD, design document, linked [UX] story, and current prototype evaluation are already available +``` + +## Starting the Workflow + +Before dispatching any phase, check if the project has its own `AGENTS.md` +or `CLAUDE.md`. If so, read it — it may contain project-specific conventions +or design system guidance that affects how the workflow operates. + +When the user provides a Jira issue key or URL: +1. Execute the **ingest** phase +2. After ingestion, present results and wait + +If the user invokes a specific command (e.g., `/evaluate`), execute that +phase directly — don't force them through earlier phases. + +## Error Handling + +If any phase fails (Jira MCP errors, skill unavailability, file errors): + +1. **Stop immediately.** Do not advance to the next phase. +2. **Report the error** to the user with the specific error message. +3. **Offer options:** retry the failed step, skip the phase (if optional), + or escalate. + +Do not fabricate results when a tool call fails. Do not silently continue +past errors. Recovery must not advance to a later phase — report the error, +re-read this controller, and wait for user direction. + +## Context Management + +When the AI detects that its own output quality is degrading (e.g., it +misses details, repeats itself, or loses track of earlier decisions), +consider spawning the current phase as a subagent with a fresh context window. +This is self-monitoring by the AI, not something a human operator watches. +Load the subagent with the skill file for the phase being executed, the +relevant artifact files from `.artifacts/ux-design/{issue-key}/`, and the +project's `AGENTS.md`/`CLAUDE.md`. + +**Important:** Spawning a subagent does not bypass the human gate between +phases. Even when a subagent completes a phase artifact, always present it +to the researcher for confirmation before advancing to the next phase per +the "Never auto-advance" rule below. + +This is a recommendation, not a requirement — not all AI runtimes support +subagent spawning. When subagent support is unavailable, manage context by +keeping phases short and relying on the artifact files to carry state between +phases. + +## 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.** Recommend `/handoff` only when `/evaluate` + covers the active prototype against the current enriched discovery revision. + An evaluation from exploratory context or an explicit skip does not satisfy + this gate. +- **Upstream skills are required.** Each phase names its required UXD skill. + If a skill is unavailable, stop and direct the researcher to run `./install.sh`. +- **Research data is the researcher's.** The AI organizes and synthesizes + but does not fabricate or extrapolate beyond what the data supports. diff --git a/ux-design/skills/evaluate.md b/ux-design/skills/evaluate.md new file mode 100644 index 00000000..9e2f1cb8 --- /dev/null +++ b/ux-design/skills/evaluate.md @@ -0,0 +1,300 @@ +--- +name: evaluate +description: Heuristic evaluation, design review, and prototype validation. +--- + +# Evaluate — Heuristic Evaluation + +Evaluate the prototype before handoff. AI-driven reviews can identify systematic +issues; only people can validate context-dependent usability with real users. + +## Dependencies + +This phase uses skills from the `uxd-research` and `uxd-prototype` plugins. If a +required skill is unavailable, stop and ask the researcher to run `./install.sh`. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/03-prototype/prototype-notes.md` for +design decisions and open questions. If it does not exist, stop and recommend +`/prototype` first. + +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for user groups and +problem framing. If `.artifacts/ux-design/{issue-key}/02-research.md` exists, +read it for user needs and insights. + +Read `00-context.md` and confirm that the active prototype has been reviewed +against the current discovery revision. If not, stop and recommend `/prototype` +to review or revise it first. Every evaluation is tied to both the prototype +iteration and discovery revision it assessed. A prior evaluation does not +validate a later prototype or a prototype assessed against newer context. + +## Process + +### Step 1: Choose Evaluation Depth + +Ask the researcher which coverage is appropriate: + +| Depth | Coverage | Skills | +|-------|----------|--------| +| **Quick** | Three independent heuristic evaluators inspect the prototype against the selected framework. | Step 2 | +| **Standard** | Quick plus structured scoring for accessibility, hierarchy, content, state coverage, and goal alignment. | Steps 2–3 | +| **Full** | Standard plus Jira acceptance-criteria validation and persona-based browser walkthroughs. | Steps 2–4 | + +Use Quick for early iterations, Standard for most reviews, and Full when the +prototype has Jira acceptance criteria and can be run in a browser. Default to +Standard. + +During Feature-only or PRD-only work, Quick and Standard are available. Full is +available only when `00-context.md` contains the linked `[UX]` story key; +never pass the Feature key in its place. + +The upstream `uxd-prototype-evaluate` skill is now an acceptance-criteria and +persona walkthrough pipeline. It no longer accepts `--depth` and no longer +produces the former desirability study. Full means that this pipeline is added +to the review; it does not mean a desirability study. + +If Full's Jira, browser, or runtime prerequisites are unavailable, tell the +researcher which prerequisite is missing and ask whether to continue at Standard. +Do not silently downgrade the evaluation. + +### Step 2: Heuristic Evaluation + +Run `uxd-research-heuristic-eval` with three independent evaluators. The skill +covers usability heuristics; it is not an accessibility audit. + +**Choose the framework first.** Ask which framework to use: + +- Nielsen's 10 Usability Heuristics +- Shneiderman's 8 Golden Rules +- ISO 9241-110 Interaction Principles +- Gerhardt-Powals' Cognitive Engineering Principles + +The skill accepts screenshots, image files, text descriptions, and URLs. For a +URL, inspect the rendered page in a live browser before invoking the skill. Do +not use curl, WebFetch, or page source as a substitute. If no live browser is +available, ask the researcher for screenshots. Do not evaluate a Figma link or +raw HTML path directly. + +For a standalone prototype, serve `.artifacts/ux-design/{issue-key}/03-prototype/prototype/` +and pass its URL. For workspace mode, run the app using the project's own +directions. If serving is not possible, capture screenshots of the important +screens and states into +`.artifacts/ux-design/{issue-key}/04-eval-raw/screenshots/`. + +Screenshots are required at Standard and Full depth because Step 3 needs them. +At Quick depth, a live URL or screenshots are sufficient. If the required input +cannot be produced, stop and explain what the researcher needs to provide. + +Run the skill in agent-operated mode so its review gate is deferred to the +single combined researcher review in Step 7. `--project` must be relative to the +source repository root: + +```bash +REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "Failed to find repository root"; exit 1; } +cd "$REPO_ROOT" +uxd-research-heuristic-eval "" \ + --framework "" --review none \ + --project ".artifacts/ux-design/{issue-key}/04-eval-raw" +``` + +`--review none` requires `--framework`. It emits an Unreviewed Draft so the +researcher can confirm findings in Step 7. Read the generated report from +`.artifacts/ux-design/{issue-key}/04-eval-raw/`. + +### Step 3: Design Heuristics Scoring (Standard and Full) + +Run `uxd-evaluate-design-heuristics` with the screenshots from Step 2. It +requires screenshots rather than a URL and returns its scores and findings +inline; it does not write a report file. Capture the returned results for the +combined report. + +This skill covers accessibility as one design-review dimension. The +`uxd-research-heuristic-eval` skill does not run accessibility scanners or score +WCAG conformance. Do not present heuristic observations as an accessibility +audit. + +### Step 4: Acceptance-Criteria and Persona Evaluation (Full only) + +`uxd-prototype-evaluate` requires the linked `[UX]` Jira story key, Atlassian +MCP access, a reachable prototype URL, Node/npm, and Playwright Chromium. It runs acceptance- +criteria validation and persona-based browser walkthroughs. It may fix failed +criteria by default, so always pass `--no-fix`; never pass `--reset` or omit +`--no-fix` in this workflow. It has no `--depth` flag. With a prototype URL but no +workspace or MR URL, its own rules require the researcher to confirm before +continuing. + +The upstream skill writes into `.artifacts/{KEY}/eval/` and `.artifacts/eval/` +under the consumer repository's Git root. Keep those files inside this +workflow's private namespace by giving the evaluator a private Git root for +each run: + +1. Create a unique run directory at + `.artifacts/ux-design/{issue-key}/04-eval-raw/prototype-evaluate/{run-id}/`. +2. Initialize a local Git repository in that directory. This makes the + evaluator's `.artifacts/` output paths resolve inside the UX Design + workflow's private artifact directory. +3. Stage the prototype's `rfe-snapshot.md` at + `{run-directory}/.artifacts/{story-key}/rfe-snapshot.md`. Stage any + `decisions/` artifacts there when available. If the consumer project has + `config/product-overlay.yaml`, copy it to the same path under the run + directory; do not invent a product overlay if it is absent. +4. Read the **Skill prototype ID** from + `.artifacts/ux-design/{issue-key}/03-prototype/prototype-notes.md` and call + it `{prototype-id}`. Keep this ID separate from the linked `[UX]` story key: + the evaluator needs the story key for Jira, while prototype refinement + needs the prototype ID for its native artifact path. +5. Run the evaluator from the run directory with `{story-key}`, prototype URL, + `--no-fix`, and `--workspace=` when a workspace clone exists: + + ```text + uxd-prototype-evaluate {story-key} "{prototype URL}" --no-fix [--workspace="{workspace path}"] + ``` + +6. Read the resulting report and evidence from + `{run-directory}/.artifacts/{story-key}/eval/`. The cross-key files are + isolated under `{run-directory}/.artifacts/eval/`. Keep those files at + their current path if `{prototype-id}` equals `{story-key}`. Otherwise, + copy `evaluation-report.csv` and `refinement-suggestions.json` into + `{run-directory}/.artifacts/{prototype-id}/eval/`, preserving the original + reports. Use the ID recorded in `prototype-notes.md`; do not substitute the + story key. If either refinement file is absent, leave it absent and let + `/prototype` follow its no-input path. Keep the run directory for review; + do not copy evaluator files to `.artifacts/{issue-key}/` at the repository + root. + +Use a fresh run directory for each evaluation. If the skill's required Jira +access, product configuration, URL, or browser runtime is unavailable, Full is +not available; ask whether to continue at Standard. + +**Runtime paths:** Upstream scripts refer to `CLAUDE_SKILL_DIR` and +`CLAUDE_PLUGIN_ROOT`. Claude Code supplies those variables. In other runtimes, +resolve the installed skill directory under +`${HOME}/.uxd-ai-skills/plugins/uxd-prototype/skills/uxd-prototype-evaluate` +and its plugin root at `${HOME}/.uxd-ai-skills/plugins/uxd-prototype`. Set the +expected variable for a helper invocation or substitute its absolute path. +Do not run helper scripts from an assumed plugin location. + +### Step 5: Cross-Reference with Research + +If `02-research.md` exists, compare evaluation findings against it: + +- Do findings align with researched user needs? +- Do usability issues conflict with prioritized needs? +- Do competitive patterns from discovery address any identified issues? + +If formal research was skipped, cross-reference `01-discovery.md` and say that +formal research findings were not available. + +### Step 6: Reconcile and Prioritize + +Gather the outputs for methods that ran: + +- Heuristic evaluation: reports under + `.artifacts/ux-design/{issue-key}/04-eval-raw/` +- Design heuristics: inline scores and findings from Step 3 +- Full prototype evaluation: `evaluation-report.html`, + `evaluation-report.csv`, and `journey-log.json` under the private run + directory from Step 4 + +Combine related findings, note how many methods identified each one, and give +unanimous findings the highest confidence. The upstream prototype evaluator +reports acceptance-criteria verdicts and persona walkthrough evidence; it no +longer assigns the previous S1–S4 severity scale. Do not infer a severity from +an acceptance-criteria verdict or persona score. The researcher sets the final +severity in Step 7. + +| Severity | Definition | +|----------|------------| +| Critical | Prevents users from completing the primary task | +| Major | Causes significant confusion or extra effort | +| Minor | Noticeable friction that does not block task completion | +| Cosmetic | Aesthetic issue with no functional impact | + +### Step 7: Researcher Review (Required) + +This is the workflow's single review gate. The upstream heuristic evaluation +runs with its review deferred; the prototype evaluator's scores and verdicts +are evidence, not researcher-approved conclusions. + +Present all findings. The researcher confirms or dismisses each one, assigns +severity, adds missing context, and chooses which issues to address or accept. +Do not make these decisions for the researcher. + +## Output + +`.artifacts/ux-design/{issue-key}/04-evaluation.md` + +Before replacing an existing `04-evaluation.md`, preserve it under +`.artifacts/ux-design/{issue-key}/history/evaluation-r{N}.md`, where `{N}` is +the prior evaluation revision, unless that exact report is already preserved +in the current context-revision snapshot. Increment the evaluation revision +for every new report. Keep each raw evaluator run in its unique `04-eval-raw/` +directory. + +Omit sections for methods that did not run. Use this structure: + +```markdown +# Evaluation Report — {issue-key} + +**Date:** {date} +**Evaluation revision:** {revision number} +**Prototype iteration:** {N} +**Discovery revision:** {revision evaluated} +**Depth:** {Quick / Standard / Full} +**Framework:** {heuristic framework} +**Methods:** {methods run} + +## Summary + +**Total issues:** {count} +**Critical:** {count} | **Major:** {count} | **Minor:** {count} | **Cosmetic:** {count} + +## Heuristic Evaluation Findings + +{From Step 2. Group findings by researcher-confirmed severity. Include the +heuristic, agreement, description, user impact, recommendation, and component.} + +## Design Heuristics Scores + +{From Step 3; omit at Quick depth.} + +| Dimension | Score | Notes | +|-----------|-------|-------| +| Accessibility | {score} | {notes; do not claim WCAG conformance} | +| Visual hierarchy | {score} | {notes} | +| Content clarity | {score} | {notes} | +| State coverage | {score} | {notes} | +| Goal alignment | {score} | {notes} | + +## Acceptance-Criteria and Persona Results + +{From Step 4; omit unless Full ran. Summarize AC pass/fail/flagged verdicts, +personas and tasks, and link to the HTML evidence report.} + +## Accessibility Findings + +{From the design heuristics review only. State when no accessibility audit was +conducted; do not derive conformance claims from the heuristic evaluator.} + +## Readiness Assessment + +**Ready for handoff:** {Yes / No — needs iteration} +**Confidence:** {HIGH / MEDIUM / LOW} +**Rationale:** {why} + +## Iteration Recommendations + +{Researcher-approved changes for the next prototype iteration, or minor items +to carry into handoff.} +``` + +## When This Phase Is Done + +Present the evaluation and readiness assessment. Ask whether the researcher +wants to iterate or move to handoff. Wait for the answer, then re-read +`controller.md` for next-step guidance. + +After the researcher confirms the report, update `00-context.md` with the +evaluated prototype iteration and discovery revision. Only an evaluation whose +revision matches the current enriched discovery can satisfy `/handoff`. diff --git a/ux-design/skills/handoff.md b/ux-design/skills/handoff.md new file mode 100644 index 00000000..6c7d12a4 --- /dev/null +++ b/ux-design/skills/handoff.md @@ -0,0 +1,333 @@ +--- +name: handoff +description: Synthesize research, prototype, and evaluation into an implementation-ready handoff spec. +--- + +# Design handoff — Implementation Spec + +Synthesize all prior artifacts into a spec that a developer can implement +from. This is the contract between the ux-design workflow and `ui-design`. + +## Dependencies + +This phase requires `uxd-design-handoff` from the `uxd-design` plugin. If the +skill is unavailable, stop and ask the researcher to run `./install.sh` before +proceeding. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/00-context.md` first. The context must +be marked `enriched` and identify the Jira Feature, a linked `[UX]` story, the +published PRD, and the published design document. A context that started from +the Feature issue or PRD alone remains exploratory and is not ready for handoff +to `ui-design`. + +Verify these artifacts exist and apply to the current context before generating: +- `.artifacts/ux-design/{issue-key}/01-discovery.md` — problem context +- `.artifacts/ux-design/{issue-key}/03-prototype/` — design prototype +- `.artifacts/ux-design/{issue-key}/04-evaluation.md` — evaluation results + +The discovery brief's context revision must match `00-context.md`. The current +prototype must be recorded as reviewed against that revision, and the +evaluation must cover that same revision and active prototype iteration. If +research was run, its findings must also have a context reconciliation for the +current revision. + +If any prerequisite is missing or stale, stop before invoking +`uxd-design-handoff` and before writing `05-handoff.md`. Explain which upstream +input or phase is missing, then recommend `/ingest`, `/research`, `/prototype`, +or `/evaluate` as appropriate. Do not offer a partial handoff or allow a +researcher override of the exploratory-context gate. The researcher can +continue the exploratory research and prototyping loop until the context is +enriched. + +Read all available artifacts before proceeding. If `02-research.md` exists, +read it — it is required for the Data Annotations and Persona-Specific Views +sections below. If it does not exist (research was skipped), record in the +Research Context section that formal research findings were unavailable and +that `01-discovery.md` supplied the evidence. + +Read `01-discovery.md` in full — in particular its **Technical Design +Context** and **Non-Functional Requirements** sections. The ingested design +document grounds the feasibility check; the PRD's NFRs feed the accessibility +requirements and acceptance criteria. If either document is listed as missing +or not ingested, the prerequisite gate fails. If a loaded document does not +specify a particular constraint, record that gap and mark the affected finding +unverified. Do not invent design constraints. + +## Process + +### Step 1: Run the UXD design-handoff skill + +Invoke the `uxd-design-handoff` skill with the prototype files and prior +artifacts as input. + +The skill handles: +- Component mapping (UI element → design system component → props/variants) +- State matrix (empty, loading, error, populated, partial, responsive) +- Interaction specs (user flows, keyboard navigation, focus management) +- Acceptance criteria in Given/When/Then format, traced to design decisions +- Accessibility requirements (WCAG, ARIA, keyboard, screen reader) +- Open questions + +Pass `--design-system patternfly` if the project uses PatternFly. Check the +top-level `package.json` for `@patternfly/react-core`; for monorepos, also +check workspace package.json files (e.g., `packages/*/package.json` or +`apps/*/package.json`). If PatternFly is found anywhere, pass the flag; +otherwise omit and let the skill auto-detect. + +Wait for the skill to complete. Review the output before proceeding. + +**Locate and read back the skill's output.** `uxd-design-handoff` writes its +result as `design-handoff-{slug}.md` (or `.json`) into the **current working +directory** — the source-repo root — with no flag to redirect it. It does not +write into our artifact namespace. So: + +1. Find the file the skill just wrote (e.g. `ls design-handoff-*.md + design-handoff-*.json` in the repo root). If more than one matches, use the + most recently modified. Store the selected file's exact path in + `handoff_output`. If no file matches after the skill reports success, stop + and report it — do not fabricate the handoff content from the other + artifacts alone. +2. Read the file at `$handoff_output` — this is the input for Steps 2-4. +3. After you have assembled `05-handoff.md` (Step 5), **move the skill's raw + output into our namespace** so it is not left untracked at the repo root. + Move only the selected file: + `mv "$handoff_output" ".artifacts/ux-design/{issue-key}/03-prototype/"` + (the source-repo `.gitignore` covers `.artifacts/` but not the repo root, so + a stray `design-handoff-*` file there can be committed by accident). + +### Step 2: Data Annotations + +The skill does not annotate data requirements per UI element. Do this manually +using the research artifacts: + +For each UI element in the component map, identify: +- What data does it display? +- Where does that data conceptually come from? Classify each into one of these + source types — do **not** invent specific API endpoint names, service names, + or schema fields that you have not confirmed exist in the codebase: + - **API** — fetched from a backend service + - **User input** — entered or selected by the user in this flow + - **Configuration** — settings, feature flags, or environment values + - **Computed** — derived on the client from other data + - **Static** — hardcoded labels, copy, or constants + - **Unknown** — source is unclear and `ui-design` must determine it +- Flag any UI state that likely has no backend support (for `ui-design` to + investigate at implementation level) + +Describe the source conceptually (e.g., "API — the list of active sessions"). +Only name a concrete endpoint or field when you have verified it in the +codebase during `/ingest`; otherwise use the conceptual type and leave the +specifics for `ui-design`. + +Use `02-research.md` user needs and `01-discovery.md` to inform which data +gaps are most likely to affect the design. + +### Step 3: Persona-Specific Views + +The skill does not document persona-specific views. Do this manually: + +Check `02-research.md` for persona notes (or `01-discovery.md` user groups +if research was skipped). If multiple user groups interact differently: +- Identify which components or flows are shared vs. persona-specific +- Document persona-specific states, actions, or views +- Note permission-gated interactions — but do **not** invent permission systems + or specific permission names that you have not confirmed exist in the codebase + or design document. Describe permission requirements conceptually (e.g., "admin- + only action") unless you have verified the actual permission model. + +If all user groups interact identically, state that explicitly. + +### Step 4: Feasibility and Phasing Check + +A design that the feature's architecture cannot support is not +implementation-ready. Reality-check the proposed design against the +**Technical Design Context** captured in `01-discovery.md` (architecture, API +shapes, data models, cross-component interactions) before finalizing. + +Start from the backend gaps already flagged in Step 2 (Data Annotations) — do +not re-derive them independently. Step 2 flags, per UI element, data whose +source is uncertain or likely unsupported; Step 4 reconciles those flags +against the technical design and presents the single, authoritative backend-gap +list. If Step 4 surfaces a gap Step 2 missed, add it back to the Data +Annotations table so the two sections stay consistent. + +For each major design element (from the component map, interaction specs, and +the Data Annotations gaps), determine whether the technical design supports it: + +- **Supported** — the architecture, an existing API shape, or an existing data + model backs it. No action. +- **Needs backend support** — the element implies data, an endpoint, or a field + the design document does not describe (e.g., "the list needs a child-resource + count, but no aggregation field exists"). Record it as a structural + observation for `ui-design`/`design` to turn into a `[DEV]` item — do **not** + invent the endpoint or field here. +- **Requires a design change** — the gap reshapes the UX itself (e.g., a filter + the API cannot express). Flag it; the researcher decides whether to adjust + the design or accept it as a backend requirement. + +If the collected constraints mean the full design cannot be delivered in one +feature, do **not** silently drop scope. Following the workflow's no-scope- +reduction rule, record a **Final Vision** (the complete intended UX) and a +proposed **MVP / Phase 1** (what is deliverable now given the constraints), +and present the split to the researcher. The researcher owns the phasing +decision. + +If an ingested design document contains no relevant architecture, API, or data +model information, perform the check against the available **Current State** +and data-source classifications, and mark affected findings **unverified +against the technical design**. `/handoff` does no codebase exploration of its +own, so do not imply verification the phase cannot perform. + +### Step 5: Assemble the handoff artifact + +Combine the skill's output with Steps 2, 3, and 4 into the artifact below, and +save it to `.artifacts/ux-design/{issue-key}/05-handoff.md`. +Preserve the skill's Given/When/Then acceptance criteria format — it is +more precise than a flat table and `ui-design` can consume it. + +Then move the skill's raw output into the namespace and clean up the repo +root as described in Step 1. + +### Step 6: Capture Provenance + +`05-handoff.md` is a planning document published to the docs repo (via +`/publish`), so it carries the same provenance contract as `prd`/`design`. +Read and follow `../../_shared/recipes/capture-provenance-event.md` with +`WORKFLOW=ux-design`, `ISSUE_KEY={issue-key}`, `PHASE=handoff`, +`AUTHORING_MODE=skill`. + +## Output + +- `.artifacts/ux-design/{issue-key}/05-handoff.md` +- `.artifacts/ux-design/{issue-key}/provenance.json` (provenance log) + +```markdown +# Implementation Handoff — {issue-key} + +**Date:** {date} +**Feature key:** {feature-key} +**UX story key:** {story-key} +**Context revision:** {current enriched revision} +**Prototype iteration:** {iteration evaluated} +**Evaluation cycles:** {number of `/evaluate` runs} +**Design system:** {detected or specified} + +## Summary + +{One paragraph: what the feature is, who it's for, and the core UX rationale} + +## Component Mapping + +| # | UI Element | Component | Variants/Props | Notes | +|---|------------|-----------|----------------|-------| +| 1 | {element} | {component name} | {key props} | {customization needed} | + +## State Matrix + +| Component | Empty | Loading | Error | Populated | Partial | Responsive | +|-----------|-------|---------|-------|-----------|---------|------------| +| {name} | {behavior} | {behavior} | {behavior} | {behavior} | {behavior} | {behavior} | + +## Interaction Specs + +### User Flows + +{Step-by-step flows from skill output} + +### Keyboard Navigation + +{Tab order, arrow key behavior, shortcuts} + +### Focus Management + +{Where focus moves after modals close, async operations, etc.} + +## Data Annotations + +{Written in Step 2 above — not from the skill} + +| UI Element | Data Needed | Source Type | Notes / Gaps | +|------------|-------------|-------------|--------------| +| {element} | {what it displays} | {API / User input / Configuration / Computed / Static / Unknown} | {flag if backend support is uncertain} | + +## Persona-Specific Views + +{Written in Step 3 above — not from the skill. + If all user groups interact identically, state that here.} + +| User Group | Distinct Views or Actions | Permission Notes | +|------------|--------------------------|-----------------| +| {group} | {what's different} | {what's gated} | + +## Accessibility Requirements + +{From skill output — WCAG, ARIA, keyboard, screen reader notes per component. + Reconcile against the accessibility, performance, and supported-browser NFRs + captured in `01-discovery.md`; call out any NFR the design does not yet + satisfy, preserving its NFR-N ID.} + +## Acceptance Criteria + +{From skill output — Given/When/Then format, traced to design decisions} + +AC-1: {Component} — {State/Behavior} + Given {precondition} + When {action} + Then {expected outcome} + Trace: {design decision, research finding, or "Design spec"} + +## Feasibility and Phasing + +{Written in Step 4 above. State whether the design is verified against the + technical design context. Mark individual findings "unverified against the + technical design" when an ingested source does not establish the needed + constraint.} + +| Design Element | Support | Notes / Backend Requirement | +|----------------|---------|-----------------------------| +| {element} | {Supported / Needs backend support / Requires design change} | {structural observation for ui-design, or the design change} | + +{If constraints force a split, include both:} + +**Final Vision:** {the complete intended UX} + +**MVP / Phase 1 (proposed):** {what is deliverable now, and why the rest is +deferred — the researcher confirms this split} + +{If the full design is deliverable as-is, state: "No phasing required — the +technical design supports the full design."} + +## Open Questions + +{From skill output — ambiguities or gaps needing clarification} + +## Research Context + +- **Discovery:** `01-discovery.md` (context revision {revision}) +- **Research:** `02-research.md` (if available) +- **Prototype:** `03-prototype/` (iteration {N}) +- **Evaluation:** `04-evaluation.md` (context revision {revision}) +``` + +## When This Phase Is Done + +Present the handoff spec to the researcher: +"Here's the implementation handoff. Does this capture everything a developer +needs to build this feature? Any interaction details, data requirements, +or edge cases missing?" + +Wait for confirmation. The researcher may: +- Request additions or corrections → update the spec +- Approve → the workflow is complete + +After approval, update `00-context.md` to record that `05-handoff.md` is +approved against the current enriched discovery revision. + +When approved, report: +- Summary of the research cycle (phases completed, iterations) +- The handoff artifact location +- Any open questions or risks for implementation + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/ingest.md b/ux-design/skills/ingest.md new file mode 100644 index 00000000..0e5b1cfa --- /dev/null +++ b/ux-design/skills/ingest.md @@ -0,0 +1,489 @@ +--- +name: ingest +description: >- + Start exploratory work from a Jira Feature or published PRD, then enrich it + with design and UX story inputs. +--- + +# Ingest — Discovery and Context Enrichment + +Load the available feature context, frame the problem, identify who it affects, +and survey how others have solved it. A Jira Feature or an explicitly supplied +published `prd.md` can seed early research and exploratory prototyping before +the design document or linked `[UX]` story exists. Those artifacts remain +exploratory until `/ingest` enriches the same context with the design document +and linked `[UX]` story. + +Use the Feature key as the stable artifact key for all work on that feature. +When ingest starts from a PRD path, identify the Feature key from its Jira +metadata or feature-directory name. If neither identifies one, ask the +researcher for the Feature key to use as the stable context key before creating +artifacts. When ingest starts from a `[UX]` story, resolve its Feature key and +use that Feature's artifact directory; keep the story key as a separate linked +input. + +## Dependencies + +This phase requires `uxd-discovery` from the `uxd-research` plugin. If the +skill is unavailable, stop and ask the researcher to run `./install.sh` before +proceeding. + +## Shared-input rule + +The person running `ux-design` may not be the person who ran `prd` or +`design`. Every upstream input must be loaded from a **shared** location — the +published docs repo, an explicitly supplied published PRD path, or Jira — +never from another workflow's private `.artifacts/` directory +(`.artifacts/prd/`, `.artifacts/design/`). Those are +each workflow's working directories, not interfaces. + +**Failure handling:** Distinguish fatal from non-fatal input failures: + +- **Fatal (hard-stop):** The core input — a Jira Feature, a `[UX]` story, a + supplied PRD path, or a feature description — cannot be loaded or is invalid. + Stop, report the exact error, and offer to retry or ask the researcher to + supply the input directly. A PRD path that does not identify a stable context + key is incomplete; ask for one before creating artifacts. +- **Non-fatal (note and continue):** An optional input (a specific sibling + story, one document, the design system reference) is missing. Note what is + missing in the artifact, continue with what is available, and **never + fabricate** context to fill the gap. A downstream phase that depends on + missing context must flag it, not paper over it. + +Examples: Jira Feature or story fetch failure, or unreadable supplied PRD path +→ fatal. One sibling story inaccessible → non-fatal. PRD not found after +docs-repo search → non-fatal (record "Not found"). A docs-repo path that is +invalid during enrichment is fatal; during initial Feature-only exploration it +is optional, so record that planning documents could not be checked and +continue. + +## Process + +### Step 1: Identify the Feature Context + +The researcher provides one of: +- A Jira Feature issue key or URL +- A path to a published `prd.md` file +- A `[UX]` Jira story key or URL +- A feature description or problem statement + +If an existing local path named `prd.md` is supplied, treat it as the primary +input before interpreting the text as a Jira key or feature description. Resolve +relative paths from the researcher's current working directory. Resolve +symlinks before checking that the path is outside any workflow's private +`.artifacts/` directory. + +For Jira-key inputs, fetch issues read-only and inspect their issue type before +following references. A PRD-path input does not fetch Jira content. Keep the +Feature key (`{issue-key}`) separate from any linked +`[UX]` story key (`{story-key}`). `{issue-key}` names the stable artifact +directory for every phase in this feature context. If the input is a Jira +Feature, use its key. If the input is a `[UX]` story, resolve the Feature key +through the parent chain or the epic's `Feature:` Design Reference, as below. +For a PRD path, read the Jira Feature key from the PRD metadata or the parent +feature-directory name when present. If both provide keys and they conflict, +ask which Feature the PRD belongs to. If neither provides a key, ask for the +Feature key to use as the stable context key. Do not fetch Jira content just to +validate this key. For a description without a Jira Feature, ask for a stable +artifact key and prefer a supplied Feature key; otherwise use a descriptive +key such as `description-`. + +**If a Jira Feature key was provided**, fetch the Feature and use its title, +description, goals, and acceptance information as the initial source. Do not +look for a parent epic or sibling stories. If no context directory exists, this +is an initial ingest. Load published planning documents in Step 2 when a docs +repo is already configured. If no docs repo is configured, continue without +setting one up; record that PRD/design documents were not checked and skip +Steps 2–3. If the documents are not published, record that and skip Step 3. +Continue with Step 4 and produce an exploratory brief. Do not imply that a +missing PRD or design document was reviewed. + +**If a published PRD path was provided**, use that file as the primary input. +Do not fetch Jira issue content or search for sibling documents just because a +Feature key appears in the path. If the key is present in the PRD metadata or +directory name, use it as `{issue-key}`; otherwise use the Feature key the +researcher supplied as the stable context key. Do not require Jira access for +this input. In Step 2, read only the supplied PRD; record +the design document and linked `[UX]` story as not ingested. This is an initial +PRD-only ingest even when a `design.md` or story exists beside it. For an +existing context, preserve sources already recorded and add or refresh only +the supplied PRD. On later Jira-backed enrichment, confirm the resolved Feature +key matches this context's key. If it does not, stop and ask the researcher to +reconcile the context; do not silently create a parallel artifact directory. +Skip the docs-repo search for this invocation. + +**If a Jira `[UX]` story key was provided**, fetch the story (read-only — never +create or modify Jira issues) and read its **Design Reference** section. In the +`design` workflow's output, a `[UX]` story's Design Reference names: +- its **parent epic** (`Epic: Epic {N} — {title}`, resolved to the epic's Jira + key), used to fetch sibling stories, +- the **PRD requirements** it traces to (FR-N / NFR-N IDs), and +- the relevant **design document sections**. + +The story does **not** name the feature key, but the docs repo publishes +`prd.md`/`design.md` under the **feature** directory (named for the Feature +issue), so you must resolve the feature key before Step 2 can find them. The +Jira hierarchy is fixed: **Feature → Epic → Story**. Resolve the feature key by +one of: +- fetching the **parent epic** issue (read-only) and reading its Design + Reference `Feature: {feature-key}` line (the epic file carries it, the story + does not), or +- walking the Jira parent chain Story → Epic → Feature and using the Feature + issue key. + +Record the Feature key as `{issue-key}`, the `[UX]` story key as `{story-key}`, +and the parent epic key separately. Also record the referenced requirement and +design-section IDs. These are distinct issues; do not use the story key or epic +key as the artifact-directory key or docs lookup key. + +If the story has no Design Reference (or no parent epic), or the Feature key +cannot be resolved, note that upstream tracing is unavailable and ask the +researcher for the Feature key or the PRD/design paths. Do not silently create a +story-key artifact directory when this feature already has a context directory. + +**If only a feature description or problem statement was provided**, there is +no Jira issue to trace. Skip reference-following and sibling lookup, record that +the PRD and design document were not ingested, and continue with an exploratory +brief. Do not use a descriptive artifact key for Jira queries or imply that a +Jira issue exists. + +**When a context directory already exists**, treat this invocation as context +enrichment only when it adds a newly available PRD, design document, or linked +`[UX]` story. A PRD-path invocation adds only the supplied PRD; it does not +implicitly ingest co-located clarifications, design, or story files. +Read `00-context.md` and the current discovery, research, +prototype, and evaluation artifacts before writing. If the same sources are +already recorded and their contents are unchanged, resume the current context +without incrementing its revision. Compare document content and available +version or last-updated metadata, not only paths. When inputs have changed, +increment the context revision and preserve the previous active artifacts under +`history/context-r{N}/` before replacing any current artifact. Never overwrite +a history snapshot. + +### Step 2: Load the PRD and Design Document + +The published PRD and design document are the authoritative upstream inputs. +They live together in the docs repo under the **feature** directory (named for +the Feature issue, e.g., `v2.1/delta-updates-EDM-4867/`), as `prd.md` +and `design.md` — *not* under the epic key or the `[UX]` story key. + +For a direct PRD-path input, use the path supplied in Step 1 and skip docs-repo +configuration and search. Confirm the file is readable, its basename is +`prd.md`, and its resolved path is outside every workflow's private +`.artifacts/` directory. An explicitly supplied path is treated as the shared +published source; Jira access and docs-repo configuration are not required. +Record the resolved path. Read only that PRD; record the design document and +linked `[UX]` story as not ingested, even if sibling files exist. This +completes Step 2 for PRD-path input; do not continue to the docs-repo +configuration or search subsections below. + +#### Resolve the docs repo + +For Feature-key and `[UX]` story inputs, read `.artifacts/config.json` for +`docs_repo_path` and `docs_repo_remote`. Direct PRD-path inputs use the bypass +described above. + +The `docs_repo_path` is stored **relative to the source-repository root** so +the config is portable across machines. Resolve it to an absolute path at +runtime for validation and use. + +**If the config exists**, resolve the relative path to absolute (relative to +the source-repository root), then validate: the path exists, it is a git +repository, and its remote URL matches `docs_repo_remote`. If validation fails +during initial Feature-only exploration, record that the docs repo could not +be checked and continue. Otherwise, tell the researcher and re-ask for the +correct path and remote. Revalidate the new path and remote using the same +checks (path exists, is a git repository, remote URL matches). After successful +validation, convert the new path to relative (from source-repository root) and +persist **both** the corrected `docs_repo_path` and replacement +`docs_repo_remote` to `.artifacts/config.json`. + +**If the config does not exist**, an initial Jira Feature ingest can continue +without docs-repo setup: record that planning documents were not checked and +skip this step. For a `[UX]` story ingest or context enrichment, ask for the +docs repo local path and remote, validate them (resolve `~` first), then +convert the path to relative (from source-repository root) and write +`.artifacts/config.json`. + +Example conversion: +``` +Source repository root: /home/user/src/myproject +Docs repository path: /home/user/src/myproject-docs +Store in config.json: ../myproject-docs +``` + +#### Find and read the documents + +Search the docs repo for the feature directory using the **feature key** +resolved in Step 1 (not the epic key and not the `[UX]` story key — docs are +published under the feature directory only): + +```bash +find "{docs_repo_path}" -type d -name "*{feature-key}*" +``` + +Filter matches to directories containing `prd.md` — the PRD is the anchor +document (the `design` workflow publishes `design.md` alongside it), mirroring +`design`'s own resolution. If exactly one matches, read `prd.md` and, when +present in the same directory, `design.md`. If multiple match, present them and +ask which holds the current feature docs. If none match during an initial +Feature ingest, record that the planning documents are not published and +continue exploratory work. Otherwise, if no match exists or the Feature key +could not be resolved, ask the researcher for the docs directory (or the +`prd.md`/`design.md` paths) directly; do not guess. For enrichment, verify each +required file exists and is readable before reading it. + +Read what you find: +- **`prd.md`** — extract the user personas, feature goals, and non-functional + requirements that shape design decisions: accessibility targets, performance + expectations, and supported browsers/devices. Preserve FR-N / NFR-N IDs so + the handoff can trace acceptance criteria back to them. +- **`design.md`** — extract architecture context, API shapes, data models, and + cross-component interactions. This is what grounds the handoff's data + annotations in real structures and lets `/handoff` reality-check the design + against what the architecture supports. +- **`clarifications.md`**, if present alongside the PRD — note any locked + decisions; they are binding constraints on the design. + +Record the resolved paths (PRD, design, clarifications) in the artifact so +downstream phases don't repeat the lookup. If a document is genuinely absent +(e.g., design not yet published), record that it was not found — do not +substitute assumptions for it. + +### Step 3: Load Sibling Stories + +For a `[UX]` story input, understand how it fits into the broader feature so +the design neither duplicates nor conflicts with adjacent work. Using the +parent epic from Step 1, fetch the other stories in the same epic (read-only) — +the `[UX]`, `[UI]`, and `[DEV]` siblings. If the input is a Feature, PRD path, +or description without a linked story, record that story-level scope is not +yet available and skip this step. + +For each sibling, capture just enough to map the boundaries: +- its type and one-line summary, +- whether it overlaps this story's surface, and +- any explicit blocking dependency (e.g., a `[UI]` story blocked by this one). + +If Jira is unavailable or the epic cannot be traversed, note that sibling +context is missing and continue. + +### Step 4: Read Project Configuration and Design System + +Read these from the source repo if present — they tell you the project's +actual conventions and design system, so the deliverable uses real components +rather than generic ones: +- `AGENTS.md` and `CLAUDE.md` — project conventions and AI guidance +- `docs/` — existing architecture and UI documentation +- Design-system / component-library references (e.g., PatternFly usage in + `package.json`, a local design-system doc, or a component index) + +Capture the design system name, the component set available, and any design +tokens or patterns the project standardizes on. + +### Step 5: Run UXD Discovery + +Invoke the `uxd-discovery` skill with the input source (the `[UX]` story key, +Feature key, supplied PRD path, feature description, or problem statement) +**plus the upstream context loaded above**. In an initial Feature-only ingest, +use only the Feature content; in an initial PRD-only ingest, use only the PRD. +Clearly label resulting assumptions and strategic decisions as exploratory. +When enriching an existing context, use the newly loaded PRD, design document, +story, and sibling context to update the prior framing rather than treating +discovery as a fresh feature. + +The skill handles: +- Problem statement framing +- User group identification (goals, pain points) +- Strategic decisions (themed, with business outcomes and timelines) +- Competitive landscape survey +- Constraints and assumptions + +Wait for the skill to complete and present its output. Confirm understanding +with the researcher before proceeding. + +### Step 6: Current State (Codebase Exploration) + +The skill does not explore the codebase. Do this manually, focused on the +affected UI area and the design system: +- What pages or views exist today in this area? +- What components (from the project's design system) are already used? +- What user flows currently exist? + +If an optional external operation fails (one sibling story inaccessible, one +codebase file unreadable): note what failed, continue with available data, and +never fabricate context to fill the gap. If a core operation fails (Feature or +story identity unresolvable, supplied PRD unreadable, docs repo path invalid +during enrichment): stop per the failure-handling rule above. + +### Step 7: Assemble the Discovery Artifact + +Combine the loaded upstream context, the skill's output, and the codebase +exploration into the artifact below. Preserve the skill's Strategic Decisions +structure exactly — do not flatten or reformat its themed format. Where an +upstream input was not found, write "Not found" (and why) rather than omitting +the section — a downstream phase needs to know the gap exists. + +## Output + +`.artifacts/ux-design/{issue-key}/01-discovery.md` + +Maintain `.artifacts/ux-design/{issue-key}/00-context.md` as the context +manifest. It records the Feature key, linked `[UX]` story key(s), current +context revision, context state (`exploratory` or `enriched`), source-document +paths, the active research basis, and the prototype iteration and evaluation +that have been reviewed against the current context. + +Use the Feature key as `{issue-key}` for all artifacts in this feature context. +For a description without a Jira Feature, use the stable key agreed in Step 1. +Create context revision 1 on the first ingest. Mark the context `exploratory` +when the PRD, design document, or linked `[UX]` story has not been ingested. +Mark it `enriched` only after the PRD and design document are loaded and a +linked `[UX]` story is recorded. Add `Context revision` and `Context state` to +`01-discovery.md`. + +When enriching an existing context, preserve the previous active artifacts +under `.artifacts/ux-design/{issue-key}/history/context-r{N}/` before replacing +any current artifact. Include the current manifest, discovery brief, research +findings, prototype, and evaluation when present. Do not overwrite a history +snapshot. Include an existing handoff in the snapshot and mark it stale in the +current manifest after the revision changes. After comparing old and new inputs, add a context-change assessment +to `00-context.md`: list what changed and whether prior research findings and +prototype decisions are retained, need revalidation, or are superseded. Mark +research as requiring review until its findings are reconciled, keep the +prototype's latest-reviewed revision unchanged until `/prototype` reviews it, +and mark evaluation and any prior handoff stale for the new revision. A prior +evaluation becomes current only after `/evaluate` assesses the active prototype +against the current revision. The assessment guides the next phase; it does not +make carry-forward decisions for the researcher. + +Use this structure for `00-context.md`: + +```markdown +# UX Design Context — {feature-key-or-stable-key} + +- **Feature key:** {key or "None — description-based context"} +- **Linked [UX] story keys:** {keys or "None yet"} +- **Context revision:** {number} +- **Context state:** {exploratory / enriched} +- **PRD:** {path or status} +- **Design document:** {path or status} +- **Active research:** {research revision, discovery revision, current/review required} +- **Active prototype:** {iteration, original discovery revision, latest reviewed revision} +- **Active evaluation:** {evaluation revision, prototype iteration, discovery revision, depth, current/stale} +- **Active handoff:** {discovery revision, pending/approved/stale or "Not generated"} + +## Context Change Assessment + +{For each enrichment, summarize the new inputs and their impact on prior +research, prototype decisions, and evaluation results.} +``` + +```markdown +# Discovery — {issue-key} + +**Date:** {date} +**Source:** {Feature key, [UX] story key, supplied PRD path, feature description, +or problem statement} +**Context revision:** {revision number} +**Context state:** {exploratory / enriched} +**Parent epic:** {epic key, or "None / not traced"} +**Feature:** {feature key, or "None / not resolved"} + +## Upstream References + +- **PRD:** {resolved docs-repo path, or "Not found — "} +- **Design document:** {resolved docs-repo path, or "Not found — "} +- **Clarifications:** {resolved path, or "None published"} +- **Traced requirements:** {FR-N / NFR-N IDs from the story's Design + Reference, or "None traced"} + +## Problem Statement + +{From skill output — 1-2 paragraphs: what problem, for whom, why it matters} + +## PRD Context + +{From the PRD. If not found, state that and why.} + +- **Personas:** {who the feature is for} +- **Feature goals:** {what success looks like} +- **Locked decisions:** {from clarifications, if any — binding constraints} + +### Non-Functional Requirements + +{Accessibility targets, performance expectations, supported browsers/devices — + preserve NFR-N IDs. These flow into the handoff's accessibility requirements + and acceptance criteria. If the PRD specifies none, say so.} + +## Technical Design Context + +{From the design document — this grounds the feasibility check in /handoff. + If not found, state that and why; the context remains exploratory and the + handoff gate stays closed.} + +- **Architecture:** {relevant components and how they interact} +- **API shapes:** {endpoints/contracts the UI will consume, at the structural + level — do not invent fields} +- **Data models:** {existing structures the UI displays or manipulates} +- **Cross-component interactions:** {how this piece connects to adjacent work} + +## Sibling Stories + +{From the epic. If not traced, say so.} + +| Story | Type | Summary | Overlap / Dependency | +|-------|------|---------|----------------------| +| {key} | {[UX]/[UI]/[DEV]} | {one line} | {shared surface, blocking dep, or none} | + +## Design System + +{Name of the design system, available component set, and tokens/patterns the + project standardizes on. From Step 4. If none is defined, state that.} + +## User Groups + +### {Group Name} +- **Description:** {who they are} +- **Goals:** {what they want to accomplish} +- **Pain points:** {current frustrations} + +## Current State + +{What the product does today in this area. Include relevant file paths + or component references from the codebase. Written in Step 6 above.} + +## Strategic Decisions + +{From skill output — themed, with business outcomes and timelines. + Preserve the skill's structure exactly.} + +## Competitive Landscape + +{From skill output} + +## Constraints + +{From skill output, plus any binding constraints from the design document or + PRD locked decisions.} + +## Assumptions to Validate + +{From skill output — framed as testable hypotheses} +``` + +## When This Phase Is Done + +Present the discovery brief to the researcher: +"Here's the problem framing with the PRD and design context it's grounded in, +the user groups, and the competitive landscape. Does this capture the right +scope? Any user groups, competitors, strategic decisions — or upstream context +— missing or wrong?" + +Call out explicitly any upstream input that was **not found**, so the +researcher can decide whether to supply it before proceeding. + +Wait for confirmation. Then write the approved revision and context state to +`00-context.md`, and **re-read the controller** (`controller.md`) for next-step +guidance. When this was an enrichment, present the context-change assessment +and wait for the researcher to confirm the carry-forward plan before +recommending further research, prototyping, or evaluation. diff --git a/ux-design/skills/prototype.md b/ux-design/skills/prototype.md new file mode 100644 index 00000000..4bd2ca15 --- /dev/null +++ b/ux-design/skills/prototype.md @@ -0,0 +1,257 @@ +--- +name: prototype +description: Generate design prototypes informed by research findings for evaluation. +--- + +# Prototype — Design Exploration + +Generate prototypes that let the researcher react to a design direction and +iterate before handoff. A prototype should focus on the riskiest user flows and +states rather than polish that cannot yet be validated. + +## Dependencies + +This phase requires `uxd-prototype-create` from the `uxd-prototype` plugin. If +the skill is unavailable, stop and ask the researcher to run `./install.sh`. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for the problem, user +groups, and competitive landscape. If it is missing, ask for an equivalent +problem framing. If none is available, recommend `/ingest` and stop. + +Read `00-context.md` when present. Record the discovery revision and research +synthesis used for each prototype iteration. If the context was enriched after +the current prototype was created, compare its decisions with the current +discovery and research reconciliation. Present which flows and decisions can +carry forward and which need revision; wait for the researcher to approve the +direction. An early prototype is a reference for exploration, not a validated +design for the enriched context. + +When returning from `/evaluate`, read `04-evaluation.md` and use the +researcher-approved findings to guide the next iteration. + +## Process + +The create skill conducts its own onboarding and extracts user stories. This +phase sets a strategic direction from discovery and research, supplies the +answers already agreed with the researcher, and maps the generated artifacts +into the UX Design namespace. + +### Step 1: Set the Design Direction + +Using `01-discovery.md` and `02-research.md` when present, propose one or two +design directions. For each, identify the user needs it prioritizes, the core +interaction pattern, its tradeoffs, and how it compares with patterns from +discovery. Present the directions and wait for the researcher to choose or +suggest another. + +Settle the create skill's onboarding answers with the researcher: + +- **Source:** Jira RFE, published PRD path, Figma link, feature description, + or idea from discovery. + Pass a Figma link directly to `uxd-prototype-create`; it reads Figma itself. + Do not also run `uxd-figma-read` for the same source. +- **Workspace:** `standalone` or a local path / Git URL for the codebase to + prototype in. The create skill clones a workspace into its artifact area. +- **Decisions:** use `human` for an initial prototype so the researcher chooses + among design options; use `auto` for a refinement when the researcher wants + the skill to recommend options. `skip` is the upstream default and means no + decision kit, so pass a choice explicitly. + +### Step 2: Generate the Prototype + +Invoke the skill with the source and agreed choices. For example: + +```text +uxd-prototype-create "{source}" --workspace "{path-or-standalone}" --decisions human +``` + +For a refinement, use the same prototype ID and `--decisions auto` after +staging current evaluator artifacts described below. If the discovery revision +changed since the evaluation, do not feed that stale evaluation into the +refinement; use the researcher-approved context and design feedback instead. +`--workspace` is the codebase to build in; `--target` is only a later MR/PR +destination. Do not pass a target unless the researcher requested publishing +and approved the destination. + +Keep the scope focused on: + +- The primary user flow +- Important empty, loading, error, and populated states +- The user need with the greatest uncertainty or risk + +The new create skill also records user journeys and page scenarios. Preserve +those artifacts because its evaluate and export skills consume them. + +**Runtime paths:** Upstream skill files refer to `CLAUDE_SKILL_DIR` and +`CLAUDE_PLUGIN_ROOT`. Claude Code supplies those variables. In other runtimes, +resolve the installed create skill at +`${HOME}/.uxd-ai-skills/plugins/uxd-prototype/skills/uxd-prototype-create` and +the plugin root at `${HOME}/.uxd-ai-skills/plugins/uxd-prototype`. Set the +expected variable for a helper invocation or substitute its absolute path. +Do not assume a plugin path based on another runtime. + +### Refinement After `/evaluate` + +`uxd-prototype-create refine {ID}` now reads +`.artifacts/{ID}/eval/evaluation-report.csv` and +`.artifacts/{ID}/eval/refinement-suggestions.json`. It no longer reads +`reviews/summary.md` or accepts the former `--mode` flag. + +Before refining: + +1. Restore the prototype's native layout under `.artifacts/{ID}/` from the + mirrored files in `03-prototype/` as described in Step 3. +2. If Full evaluation ran and both refinement inputs exist, copy + `evaluation-report.csv` and `refinement-suggestions.json` from the private + evaluator run directory + (`04-eval-raw/prototype-evaluate/{run-id}/.artifacts/{ID}/eval/`) into + `.artifacts/{ID}/eval/`. If either input is missing, do not invent it or + use `refine`; start a new `uxd-prototype-create` run with the source and + researcher-approved feedback as context. +3. Before a refinement or replacement changes the native prototype, preserve + the current + `.artifacts/ux-design/{issue-key}/03-prototype/` tree under + `history/prototype-iteration-{N}/`, unless that exact tree is already in the + current context-revision snapshot. Do not overwrite an existing snapshot. + +Use `refine` only when both evaluator inputs are staged: + +```text +uxd-prototype-create refine {ID} --decisions auto +``` + +Keep either the refined output or the new prototype output under +`.artifacts/{ID}/` until Step 3 mirrors it. Do not mirror output or remove the +native directory in this step. + +### Step 3: Map Skill Output Into Our Artifact Structure + +The create skill writes to `.artifacts/{ID}/`, where `{ID}` is the Jira key or a +slug. For a refinement, Step 2 has already preserved the prior active tree; +reuse that snapshot and do not archive it again. For any other replacement, +preserve the current tree under +`.artifacts/ux-design/{issue-key}/history/prototype-iteration-{N}/` before +mirroring, unless that exact tree is already preserved in the current +context-revision snapshot. Never archive the new output as the previous +iteration. Mirror the new output under +`.artifacts/ux-design/{issue-key}/03-prototype/`, preserving the prototype's +native layout so a later refinement can restore it without flattening files. + +**Standalone prototype:** + +- `.artifacts/{ID}/prototype/` → `03-prototype/prototype/` + +**Workspace prototype:** + +- `.artifacts/{ID}/code/` contains the cloned codebase and prototype changes. + Preserve it under `03-prototype/code/` or record its durable path; note the + prototype's app entry point in `prototype-notes.md`. +- Mirror `changeset.md` and `workspace-analysis.json` to `03-prototype/`. + +**Create metadata:** mirror each file when the skill produces it: + +- `rfe-snapshot.md` +- `metadata.json` +- `user-stories.json` +- `journeys.json` +- `scenarios.json` +- `prototype-summary.yaml` +- `prototype-bar.json` +- `verification.json` +- `decisions/` and `exports/`, when present + +`rfe-snapshot.md` and `metadata.json` are required. If either is missing, stop +and report that prototype creation did not complete. The new evaluator can +consume `rfe-snapshot.md` and `decisions/` when staged into its private run +root. Record the create skill's `{ID}` in `prototype-notes.md`. + +After mirroring the canonical prototype files, remove the native +`.artifacts/{ID}/` created by the create or refine skill. This cleanup happens +only here, after the refined output is safely mirrored. The evaluator uses a +separate private run root under `04-eval-raw/`; do not move its outputs into +`.artifacts/{ID}/` except for the two temporary refinement inputs described +above. + +## Step 4: Document Design Rationale + +For each significant design decision, connect it to a research finding or +researcher direction. If neither supports it, identify it as an assumption. +Do not invent research evidence. + +## Output + +`.artifacts/ux-design/{issue-key}/03-prototype/` + +```text +03-prototype/ +├── prototype-notes.md # Direction, rationale, and open questions +├── iteration-{N}.md # Notes for each iteration +├── prototype/ # Standalone prototype, when applicable +├── code/ # Workspace clone and prototype, when applicable +├── user-stories.json # User stories and acceptance criteria +├── journeys.json # Primary user journeys +├── scenarios.json # On-load scenarios per page +├── rfe-snapshot.md # Frozen source requirements +├── metadata.json # Prototype metadata and decision mode +├── prototype-summary.yaml # Machine-readable summary +├── prototype-bar.json # Prototype Bar configuration +├── changeset.md # Workspace mode only +├── workspace-analysis.json # Workspace mode only +├── verification.json # Workspace mode only +├── decisions/ # When decisions are auto or human +└── exports/ # When export was requested +``` + +`prototype-notes.md` records: + +```markdown +# Prototype — {issue-key} + +**Date:** {date} +**Iteration:** {N} +**Discovery revision:** {revision used to make this iteration} +**Research basis:** {research revision/findings or "Research skipped"} +**Revalidated against discovery revision:** {revision or "Not yet revalidated"} +**Skill prototype ID:** {ID} +**Design direction:** {chosen direction} +**Prototype mode:** {standalone / workspace} +**Decision mode:** {skip / auto / human} +**Input source:** {Jira RFE / published PRD / Figma / feature description / idea} + +## Design Decisions + +| Decision | Rationale | Research Reference | +|----------|-----------|-------------------| +| {what} | {why} | {finding or researcher direction} | + +## 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 not represented} + +## Open Questions for Evaluation + +- {What should the evaluator focus on?} +- {Where is the design most uncertain?} +``` + +Present the prototype and its scope to the researcher. Wait for feedback before +revising or recommending `/evaluate`, then re-read `controller.md` for +next-step guidance. + +Update `00-context.md` with the active prototype iteration and the discovery +revision it has been reviewed against. If the design is materially changed, +increment the iteration and preserve the prior tree first. If no design change +is needed after enrichment, record the review against the new discovery +revision without changing the prototype's original iteration or basis. diff --git a/ux-design/skills/publish.md b/ux-design/skills/publish.md new file mode 100644 index 00000000..4a07d137 --- /dev/null +++ b/ux-design/skills/publish.md @@ -0,0 +1,294 @@ +--- +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 researcher. +- **Draft PR** — always create as a draft; the researcher 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 + +Run `git rev-parse --show-toplevel` from anywhere inside the source repo and +store its output in the `source_repo_root` shell variable. If this command +fails, stop and ask the researcher to open the source-repo workspace. Resolve +all source-repo artifact paths below against this root. + +Before reading the handoff or constructing any path containing `{issue-key}`, +require the entire value to match `[A-Za-z0-9][A-Za-z0-9._-]*`. If it does not, +stop and ask the researcher for a valid artifact key. This keeps the key to a +single path component. + +### Step 1: Read the Handoff Spec + +Read `{source_repo_root}/.artifacts/ux-design/{issue-key}/05-handoff.md`. + +If the file doesn't exist, tell the researcher that `/handoff` should be run first. + +Read `{source_repo_root}/.artifacts/ux-design/{issue-key}/00-context.md` and +verify that the context is `enriched` and the handoff +is approved against the current discovery revision. If the manifest marks the +handoff stale or its revision differs, stop and recommend `/handoff` before +publishing. Never publish a handoff produced from exploratory context. + +### Step 2: Resolve Docs Repo + +Check for an existing docs repo configuration at +`{source_repo_root}/.artifacts/config.json`. + +The shared config stores `docs_repo_path` relative to `{source_repo_root}`. +Resolve a relative configured or researcher-supplied path against +`{source_repo_root}`; keep an absolute path absolute. Use the normalized +absolute result as runtime `{docs_repo_path}` for all validation, `git -C` +commands, filesystem paths, and provenance targets below. Never pass the raw +relative config value to Git or file operations. + +**If the config exists**, read its `docs_repo_path` and `docs_repo_remote`. +**If it does not exist**, ask the researcher where the planning docs repo is +checked out, accepting an absolute path or one relative to +`{source_repo_root}`. + +Resolve the candidate path against `{source_repo_root}` if it is relative. Verify +that the resolved path exists and is a git repository. If either check fails, +stop, report the failed check, and ask the researcher to correct the path before +continuing. Run `git -C "{docs_repo_path}" remote get-url origin` to read the +actual remote. When a config already exists, verify this URL matches its +`docs_repo_remote`. When no config exists, confirm the URL with the researcher +and use it as `docs_repo_remote`. + +If reading or validating the remote fails, stop before publishing, report the +error or mismatch, and ask the researcher to correct the path or remote. Re-run +all validations after the correction. Do not write or update the shared config +while validation is failing. Once the path and remote pass validation, save +`docs_repo_path` relative to `{source_repo_root}` and `docs_repo_remote` to the +shared config. Keep using the resolved absolute `{docs_repo_path}` for the rest +of this phase. + +Derive `{owner}/{repo}` from the remote URL (e.g., +`git@github.com:org/repo.git` → `org/repo`). +Validate `{owner}` and `{repo}` separately as single components using +`[A-Za-z0-9][A-Za-z0-9._-]*`; stop if either component is invalid. + +### Step 3: Pre-Flight Checks + +Verify the environment: + +```bash +gh auth status +``` + +```bash +git -C "{docs_repo_path}" remote -v +``` + +```bash +git -C "{docs_repo_path}" status --porcelain +``` + +If the output is not empty, stop and tell the researcher the docs repo has +uncommitted changes that must be resolved before publishing. Do not proceed +with a dirty working tree. + +Confirm with the researcher: +- **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 researcher override + +Before using `{base-branch}` or `{branch-name}` in shell commands, require each +to match `[A-Za-z0-9][A-Za-z0-9._/-]*`. Then validate both as Git branch names: + +```bash +git -C "{docs_repo_path}" check-ref-format --branch "{base-branch}" +git -C "{docs_repo_path}" check-ref-format --branch "{branch-name}" +``` + +If either command fails, ask the researcher for a valid branch name. Also reject +`main` and the selected `{base-branch}` as the feature branch name; ask for a +different value before continuing. + +Before building commands from `{release}` or `{feature}`, require each value to +match `[A-Za-z0-9][A-Za-z0-9._-]*` so each is a single safe path component. +Set `docs_repo_root = Path(docs_repo_path).resolve()`, +`destination_dir = (docs_repo_root / release / feature).resolve()`, and +`handoff_target = (destination_dir / "handoff.md").resolve()`. Require +`destination_dir.relative_to(docs_repo_root)` to succeed and return a non-`.` +relative path. Apply the same containment check to `handoff_target`. +If either check fails, stop and report that the destination is outside the docs +repo. This check also catches existing symlinks that point outside the +repository. +Use the resolved destination paths for filesystem operations and the provenance +target below. + +The handoff spec file path in the docs repo: `{release}/{feature}/handoff.md`. + +### Step 4: Create Branch and Commit + +All git operations run against the **docs repo**. Use +`git -C "{docs_repo_path}"` for all commands. + +```bash +git -C "{docs_repo_path}" checkout -b "{branch-name}" "{base-branch}" +``` + +```bash +mkdir -p "{destination_dir}" +``` + +```bash +cp "{source_repo_root}/.artifacts/ux-design/{issue-key}/05-handoff.md" "{handoff_target}" +``` + +Read and follow `../../_shared/recipes/render-provenance-footer.md` with +`WORKFLOW=ux-design`, `ISSUE_KEY={issue-key}`, +`TARGET_FILE="{handoff_target}"`. + +Provenance at publish time: +- If the provenance event log at + `{source_repo_root}/.artifacts/ux-design/{issue-key}/provenance.json` contains + any non-`commit` event, the footer reflects the full authoring session + (`provenance_kind: session`). The ux-design authoring phases are `/handoff`, + `/revise`, `/respond`, and `manual-edit`. +- If the log is missing, the render recipe **auto-captures a commit-time + snapshot** (`phase=commit`, `provenance_kind: commit_only`) so stale footers + are replaced instead of copied forward. +- If the existing log contains only `commit` events, the render recipe refreshes + the commit-time snapshot and keeps `provenance_kind: commit_only`. +- Only if the researcher explicitly declines provenance, pass `ALLOW_MISSING=yes` to + strip the footer and record `provenance_kind: declined`. + +```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}" +``` + +### Step 5: Prepare PR Description + +Prepare the PR description and save it to +`{source_repo_root}/.artifacts/ux-design/{issue-key}/06-pr-description.md` +(in the source repo's artifact directory): + +```markdown +## UX Design Handoff: {title} + +**Jira:** {issue-link} + +### Summary +{2-3 sentence summary of what this handoff spec covers} + +### Requesting Review On +- Component mapping accuracy +- State enumeration completeness +- Acceptance criteria clarity +- Interaction specs correctness + +### How to Review +- Comment inline on specific sections +- Flag any missing states or interaction edge cases +- Approve when the handoff spec is implementation-ready +``` + +### Step 6: Push and Create PR + +```bash +git -C "{docs_repo_path}" push -u origin "{branch-name}" +``` + +Create a draft PR: + +Treat the title in the PR description as data; do not interpolate it into shell +source. Keep the following validated values in shell variables: + +```bash +pr_repo="{owner}/{repo}" +base_branch="{base-branch}" +branch_name="{branch-name}" +issue_key="{issue-key}" +pr_body_file="${source_repo_root}/.artifacts/ux-design/${issue_key}/06-pr-description.md" +``` + +Read the title from the PR description and invoke `gh` through a Python argument +list so the title is passed literally: + +```bash +python3 - "$pr_repo" "$base_branch" "$branch_name" "$issue_key" "$pr_body_file" <<'PY' +from pathlib import Path +import re +import subprocess +import sys + +repo, base, head, issue_key, body_file = sys.argv[1:] +if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*", repo): + raise SystemExit("Invalid GitHub owner/repo") +if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", base): + raise SystemExit("Invalid base branch") +if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", head): + raise SystemExit("Invalid head branch") +if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", issue_key): + raise SystemExit("Invalid issue key") + +body = Path(body_file).read_text(encoding="utf-8") +match = re.search(r"(?m)^## UX Design Handoff: (.+)$", body) +if not match: + raise SystemExit("PR description is missing its UX Design Handoff title") +title = f"{issue_key}: UX Design Handoff - {match.group(1).strip()}" +subprocess.run( + [ + "gh", "pr", "create", "--draft", "--repo", repo, + "--base", base, "--head", head, "--title", title, + "--body-file", body_file, + ], + check=True, + shell=False, +) +PY +``` + +### Step 7: Save Publish Metadata + +Write `{source_repo_root}/.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 Researcher + +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 + +- `{source_repo_root}/.artifacts/ux-design/{issue-key}/06-pr-description.md` +- `{source_repo_root}/.artifacts/ux-design/{issue-key}/publish-metadata.json` +- Handoff spec committed and pushed to feature branch in the docs repo +- Draft PR created against the docs repo + +## When This Phase Is Done + +Report your results: +- PR URL and branch name +- Docs repo and file location +- Suggested next steps + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/research.md b/ux-design/skills/research.md new file mode 100644 index 00000000..bd0821ec --- /dev/null +++ b/ux-design/skills/research.md @@ -0,0 +1,213 @@ +--- +name: research +description: User research, data gathering, and synthesis into insights and design recommendations. +--- + +# Research — User Research + +Conduct and synthesize user research to understand what users actually need. +The researcher drives data collection (interviews, surveys, observations); +the AI assists with organization, pattern identification, and synthesis. + +## Prerequisites + +Read `.artifacts/ux-design/{issue-key}/01-discovery.md` for the problem +framing and strategic decisions. For a Feature-scoped workflow, also read +`00-context.md` to identify the current context revision and any linked +story. If discovery doesn't exist, ask whether the researcher has equivalent +problem framing (PRD, feature brief, or description). If they do, use it as +context. If not, tell the researcher to run `/ingest` first and stop. + +If `.artifacts/ux-design/{issue-key}/02-research.md` already exists, continue +from its evidence instead of starting over. When the context revision changed, +read the archived discovery brief for the revision that informed the research +and reconcile every prior finding against the current brief. Preserve its +sources, observations, and confidence; label each finding `retained`, +`revalidate`, or `superseded`. Run only the additional research needed to +resolve new questions or revalidate affected findings. A changed product scope +can change a finding's applicability without invalidating its original evidence. + +Before replacing an existing synthesis, preserve it under +`history/research-r{N}/02-research.md`, unless that exact synthesis is already +preserved in the current context-revision snapshot. Increment the research +revision and keep the original evidence and source citations intact. For a +first research pass, mark the context reconciliation “Not applicable — first +research pass.” + +## Process + +### Stage 1: Research Plan (Interactive) + +#### Step 1: Propose Methodology + +Based on the discovery brief's strategic decisions, propose a research plan: + +- **Methods** — which research methods fit each question? (interviews, + surveys, analytics review, support ticket analysis) +- **Participants** — who should be included? How many? +- **Data sources** — what existing data can the AI analyze directly? + (support tickets, analytics, existing survey results, forum posts) + +Present the plan to the researcher. Wait for confirmation before proceeding. +The researcher knows their constraints — adapt the plan to what's feasible. + +#### Step 2: AI-Accessible Research + +While the researcher conducts interviews or observations, the AI performs +desk research that doesn't require human participants: + +- Analyze support tickets or bug reports related to the problem area +- Review forum posts, community discussions, or feedback channels +- Search for published usability studies on similar products +- Synthesize existing internal research documents + +Cite all sources. Flag confidence levels (HIGH/MEDIUM/LOW). + +**Failure modes:** If a research tool or data source is unavailable (e.g., no +MCP access to support tickets, search returns zero results, internal docs +not accessible), note what was attempted and what is missing in the research +artifact. Do not fabricate findings to fill the gap. Proceed with the +researcher-provided data (Step 3) and flag the limited desk-research coverage +in the final synthesis. + +### Stage 2: Data Organization (Collaborative) + +#### Step 3: Intake Research Data + +As the researcher gathers data (interview notes, survey responses, +observation notes), help organize it: + +- Group findings by theme, not by participant +- Identify recurring patterns across data sources +- Flag contradictions or surprising findings +- Note frequency — how many participants mentioned each theme? + +**Privacy:** Anonymize all participant data. Use role-based labels +("User P1", "Admin P2") instead of names. + +#### Step 4: Identify Patterns + +Across all data sources (researcher-gathered and AI desk research): + +- What themes appear across multiple sources? +- What user needs are consistent vs. edge cases? +- Where do different user groups have conflicting needs? +- What workarounds are users employing today? + +### Stage 3: Synthesis (Interactive) + +#### Step 5: Generate Insights + +Transform patterns into actionable insight statements: + +**Format:** "{User group} needs {capability} because {reason}, but currently +{barrier}." + +Each insight should: +- Be grounded in multiple data points +- Point toward a design direction +- Be specific enough to act on + +#### Step 6: Design Recommendations + +Based on insights, propose design recommendations: + +- What should the solution prioritize? +- What user needs are critical vs. nice-to-have? +- What design constraints emerged from research? +- What risks should the prototype address first? + +## Output + +`.artifacts/ux-design/{issue-key}/02-research.md` + +Record the discovery revision that framed this work. When updating prior +research, keep the earlier report in the history snapshot created by `/ingest` +and carry forward its evidence into the current synthesis. Do not discard or +silently rewrite earlier findings. + +```markdown +# Research Findings — {issue-key} + +**Date:** {date} +**Research revision:** {revision number} +**Methods:** {list of methods used} +**Participants:** {count and roles, anonymized} +**Discovery basis:** {context revision or equivalent framing source} + +## Context Reconciliation + +| Prior finding | Evidence retained | Disposition for current context | Follow-up | +|---------------|-------------------|---------------------------------|-----------| +| {finding} | {source/data still available} | {retained / revalidate / superseded} | {additional research or none} | + +## Research Questions & Answers + +### Q1: {strategic decision from discovery} +**Finding:** {what we learned} +**Evidence:** {data points, quotes, sources} +**Confidence:** {HIGH/MEDIUM/LOW} + +### Q2: {strategic decision from discovery} +... + +## Key Insights + +1. **{Insight title}** + {User group} needs {capability} because {reason}, but currently {barrier}. + _Evidence: {data points}_ + +2. **{Insight title}** + ... + +## User Needs (Prioritized) + +| Priority | Need | User Groups | Evidence Strength | +|----------|------|-------------|-------------------| +| Must-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | +| Should-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | +| Nice-to-have | {need} | {groups} | {HIGH/MEDIUM/LOW} | + +## Persona Notes + +{Where user groups interact differently with the feature, document + persona-specific needs here. This feeds directly into the handoff's + persona-specific views.} + +| User Group | Distinct Needs | Distinct Behaviors | +|------------|---------------|-------------------| +| {group} | {what's different for them} | {how they use the feature differently} | + +## Design Recommendations + +1. {Recommendation with rationale traced to insights} +2. ... + +## Risks & Open Questions + +- {Risk or unresolved question with impact on design} + +## Sources + +- {Source with URL or description} +``` + +## When This Phase Is Done + +Present the synthesized findings to the researcher: +"Here are the research findings and design recommendations. Do these +insights accurately reflect what you learned? Anything to add or correct +before we move to prototyping?" + +Wait for confirmation, then write the final synthesis to +`.artifacts/ux-design/{issue-key}/02-research.md`. The handoff phase reads +this file for Data Annotations and Persona-Specific Views — it must exist on +disk before returning control. + +After saving the approved synthesis, update `00-context.md` so its active +research basis matches the current discovery revision. If the researcher +chooses not to repeat research after context enrichment, record that review in +the existing synthesis and set its active basis only after they confirm the +prior findings still apply. + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/respond.md b/ux-design/skills/respond.md new file mode 100644 index 00000000..7568f937 --- /dev/null +++ b/ux-design/skills/respond.md @@ -0,0 +1,209 @@ +--- +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` (for PR discovery only — comment fetching is + delegated to the shared script) + - **Write:** delegated to `pr-comments.py reply` (do not call `gh api` + or `gh pr comment` directly for review replies) + - **Forbidden:** `gh pr close`, `gh pr merge`, `gh pr edit`, `gh pr ready` + +## Shared Script + +This skill delegates deterministic PR comment operations to a shared +script. Reference it using a relative path from this file: + +``` +../../_shared/scripts/pr-comments.py +``` + +The script provides subcommands: `fetch`, `reply`, and `log`. See the +script header for full usage. + +## Process + +### Step 1: Fetch PR Comments + +Read `.artifacts/config.json` to get the docs repo path and +`.artifacts/ux-design/{issue-key}/publish-metadata.json` to get the PR +number and `{branch-name}`. If either file doesn't exist, tell the user +that `/publish` should be run first. + +Read `00-context.md` and compare the published handoff's discovery revision +with the current revision. If enrichment made the handoff stale, stop before +applying review feedback and recommend `/handoff` to regenerate it. Resume +`/respond` after the updated handoff is approved so reviewer feedback is applied +to the current design context. + +Determine `{owner}/{repo}` from the config's `docs_repo_remote`. + +Resolve `{AI_WORKFLOWS_ROOT}` as the git root of the ai-workflows install +(typically `git rev-parse --show-toplevel` from the workflow directory, or +`~/.ai-workflows` when symlinked). Keep the source repository as the process +CWD so artifact paths remain relative to its root. Then resolve the shared +script to an absolute path: + +```bash +PR_COMMENTS_SCRIPT="{AI_WORKFLOWS_ROOT}/_shared/scripts/pr-comments.py" +``` + +Use `$PR_COMMENTS_SCRIPT` in all subsequent commands. + +Fetch all comments using the shared script. The script fetches line-level +review comments, top-level comments, and reviews in a single call and outputs +a unified JSON array to stdout: + +```bash +python3 "$PR_COMMENTS_SCRIPT" fetch --owner {owner} --repo {repo} --pr {pr-number} --responses-log .artifacts/ux-design/{issue-key}/responses.jsonl --include-review-threads +``` + +The `--responses-log` flag excludes comment IDs already addressed in prior +respond rounds. The `--include-review-threads` flag annotates line comments +with thread resolution status via GraphQL. + +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 + +**If "Handoff change needed: Yes":** + +Update `.artifacts/ux-design/{issue-key}/05-handoff.md` with approved changes. + +Read and follow `../../_shared/recipes/capture-provenance-event.md` with +`WORKFLOW=ux-design`, `ISSUE_KEY={issue-key}`, `PHASE=respond`, +`AUTHORING_MODE=skill`. + +Update the docs repo copy: + +```bash +git -C "{docs_repo_path}" checkout {branch-name} +``` + +```bash +git -C "{docs_repo_path}" pull --ff-only +``` + +```bash +cp ".artifacts/ux-design/{issue-key}/05-handoff.md" "{docs_repo_path}/{handoff_file_path}" +``` + +Read and follow `../../_shared/recipes/render-provenance-footer.md` with +`WORKFLOW=ux-design`, `ISSUE_KEY={issue-key}`, +`TARGET_FILE="{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 +``` + +**If "Handoff change needed: No":** + +Skip the git operations above — the handoff spec is unchanged. The response +is comment-only (clarification, acknowledgment, or pushback). + +**In both cases:** + +Write each approved reply to +`.artifacts/ux-design/{issue-key}/tmp-reply.md` using the host's file-writing +capability. Do not use a shell heredoc because reply content can contain the +delimiter string. + +Route each comment based on its `type` field from the fetch output. + +For a `line_comment`, reply in-thread using the comment's `id`: + +```bash +python3 "$PR_COMMENTS_SCRIPT" reply --owner {owner} --repo {repo} --pr {pr-number} --body-file .artifacts/ux-design/{issue-key}/tmp-reply.md --comment-id {id} +``` + +For a `review` or `top_level` comment, post a top-level reply: + +```bash +python3 "$PR_COMMENTS_SCRIPT" reply --owner {owner} --repo {repo} --pr {pr-number} --body-file .artifacts/ux-design/{issue-key}/tmp-reply.md +``` + +If the reply command fails, report the error and continue to the next comment +without logging the failed reply. + +After each successful reply, record its `id` so later respond rounds skip it: + +```bash +python3 "$PR_COMMENTS_SCRIPT" log --responses-log .artifacts/ux-design/{issue-key}/responses.jsonl --comment-id {id} +``` + +If logging fails, stop before posting another reply to avoid duplicate replies +on the next respond round. + +Delete the temporary reply file after a successful post and log: + +```bash +rm .artifacts/ux-design/{issue-key}/tmp-reply.md +``` + +### Step 5: Report to User + +Summarize: +- How many comments were addressed +- How many handoff spec changes were made +- Whether any comments remain unresolved + +## Output + +- PR comments posted (with user approval) +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (updated if needed) + +## When This Phase Is Done + +Report your results: +- Comments addressed and responses posted +- Handoff spec changes made +- Outstanding items + +Then **re-read the controller** (`controller.md`) for next-step guidance. diff --git a/ux-design/skills/revise.md b/ux-design/skills/revise.md new file mode 100644 index 00000000..ab2e59e9 --- /dev/null +++ b/ux-design/skills/revise.md @@ -0,0 +1,101 @@ +--- +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. If `05-handoff.md` does not exist, +stop and tell the researcher to run `/handoff` first. + +Read `00-context.md`. If the context revision changed after the handoff or the +handoff is not approved against the current enriched revision, stop and +recommend `/handoff` to regenerate it before applying stakeholder revisions. + +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (the deliverable) +- `.artifacts/ux-design/{issue-key}/04-evaluation.md` (evaluation context) +- `.artifacts/ux-design/{issue-key}/02-research.md` (research findings, if it + exists — needed to check acceptance-criteria traceability in Step 4) +- `.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 + +After writing the updated `05-handoff.md`, read and follow +`../../_shared/recipes/capture-provenance-event.md` with `WORKFLOW=ux-design`, +`ISSUE_KEY={issue-key}`, `PHASE=revise`, `AUTHORING_MODE=skill`. + +### Step 4: Consistency Check + +After applying changes, verify: +- Do acceptance criteria still trace to research findings? +- Does the component mapping still align with the prototype? +- Are interaction specs consistent with evaluation findings? +- Are there contradictions with locked research decisions? + +### Step 5: Present Changes + +Summarize what changed: + +```markdown +## Revision Summary + +### Handoff Changes +- {Section}: {what changed and why} + +### Consistency Updates +- {any cascading updates to maintain coherence} +``` + +## Output + +- `.artifacts/ux-design/{issue-key}/05-handoff.md` (updated) +- `.artifacts/ux-design/{issue-key}/provenance.json` (updated) + +## If a PR Already Exists + +`/revise` can run before or after `/publish`. If a PR already exists for this +handoff spec (check for `.artifacts/ux-design/{issue-key}/publish-metadata.json`), +the revised `05-handoff.md` is now out of sync with the published copy in the +docs repo. Do **not** push it manually — tell the researcher the spec has +changed and recommend `/respond` (or a fresh `/publish` round) to update the +PR, so the docs-repo update goes through the workflow's publish path. + +## When This Phase Is Done + +Report your results: +- What was changed and why +- Any consistency updates made as a side effect +- Whether a PR already exists and the spec now needs re-publishing +- Any remaining open questions + +Then **re-read the controller** (`controller.md`) for next-step guidance.