Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ This repository contains reusable AI coding workflows and focused skills that ca
- **ui-implement** — Story-to-code workflow for UI/front-end [UI] stories (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)
- **ux-design** — UX design workflow (ingest, research, prototype, import, evaluate, handoff, revise, publish, respond)
- **rebase-stack** — Rebase a gh-stack-tracked branch chain with health reporting, conflict guidance, trunk-adjacent validation, and atomic push (status, 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
Expand Down
41 changes: 40 additions & 1 deletion ux-design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ graph TD
enrich --> research
enrich --> prototype
enrich --> evaluate
enrich --> import_proto([import existing prototype])
import_proto --> evaluate
evaluate -->|fix at source, re-import| import_proto
evaluate -->|current context and prototype| handoff
handoff --> revise
handoff --> publish
Expand Down Expand Up @@ -58,6 +61,7 @@ and linked `[UX]` story to be ingested.
| 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/` |
| Import | `/import` | Register a prototype built outside the workflow, with any tool, as a fingerprinted snapshot, and check coverage against the current context | `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) |
Expand Down Expand Up @@ -126,6 +130,37 @@ Alternative when the PRD exists before the design document:
→ updates 05-handoff.md as needed
```

### Bring your own prototype

Teams that build prototypes with their own tools before the PRD, design
document, and `[UX]` story are final can skip `/research` and `/prototype` and
start once those inputs settle:

```text
/ingest EDM-UX
→ loads the [UX] story, the PRD, and the design document in one pass

/import --source <directory | git url | archive> --scope /page-a,/page-b
(--entry index.html | --start "<cmd>") [--ref <ref>] [--url <hosted url>]
[--baseline <product UI source>] [--notes <file>]
→ copies the prototype into 03-prototype/code/ and records a content fingerprint
→ captures the scoped screens
→ records what changed from the baseline, when one is supplied
→ checks coverage against the PRD requirements and story acceptance criteria
→ writes rfe-snapshot.md so Full evaluation can run

/evaluate
→ verifies the fingerprint, then evaluates the snapshot; fixes are made at
the prototype's source, then /import runs again

/handoff
```

`/import` does not depend on the tool that produced the prototype. Any
prototype that runs in a browser and can be supplied as files is accepted;
see `skills/import.md` § Accepted Input. The workflow never edits the
prototype's source.

After `/revise` changes a published handoff, run `/publish` again to update the
same open PR branch. Use `/respond` to address reviewer comments.

Expand All @@ -142,9 +177,11 @@ context, use the stable key agreed during `/ingest` (for example,
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)
03-prototype/ (mirrored skill output or imported prototype + design rationale)
prototype-notes.md (design decisions, user stories covered)
prototype/ (generated prototype files, from the skill)
code/ (imported prototype snapshot)
screenshots/ (imported prototype screen captures)
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)
Expand Down Expand Up @@ -225,6 +262,7 @@ ux-design/
│ ├── ingest.md # Frame problem, identify user groups
│ ├── research.md # Conduct user research
│ ├── prototype.md # Generate design prototypes
│ ├── import.md # Register an externally built prototype
│ ├── evaluate.md # Heuristic evaluation
│ ├── handoff.md # Design-to-implementation spec
│ ├── revise.md # Incorporate stakeholder feedback
Expand All @@ -234,6 +272,7 @@ ux-design/
├── ingest.md # /ingest command
├── research.md # /research command
├── prototype.md # /prototype command
├── import.md # /import command
├── evaluate.md # /evaluate command
├── handoff.md # /handoff command
├── revise.md # /revise command
Expand Down
6 changes: 3 additions & 3 deletions ux-design/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
name: ux-design
version: 0.5.0
version: 0.6.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.
Activated by commands: /ingest, /research, /prototype, /import, /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),
[import](commands/import.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
Expand Down
11 changes: 11 additions & 0 deletions ux-design/commands/import.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
name: ux-design:import
description: "Register an externally built prototype for evaluation and handoff"
---
# /import

Read `../skills/controller.md` and follow it.

Dispatch the **import** phase. Context:

$ARGUMENTS
43 changes: 34 additions & 9 deletions ux-design/skills/controller.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,23 +26,30 @@ by executing phases and handling transitions between them.
Generate design prototypes informed by discovery and research findings.
Iterative — loops with `/evaluate`.

4. **Evaluate** (`/evaluate`) — [evaluate.md](evaluate.md)
4. **Import** (`/import`) — [import.md](import.md)
Alternative to `/prototype`. Register a prototype built outside this
workflow, with any tool, as a fingerprinted snapshot, and check its
coverage against the current context. The workflow never edits the
prototype's source; the researcher fixes it at the source and imports it
again.

5. **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)
6. **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)
7. **Revise** (`/revise`) — [revise.md](revise.md)
Incorporate stakeholder feedback into the handoff spec. Repeatable.

7. **Publish** (`/publish`) — [publish.md](publish.md)
8. **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)
9. **Respond** (`/respond`) — [respond.md](respond.md)
Fetch and address PR reviewer comments on the published handoff spec.

## Workspace
Expand All @@ -65,12 +72,12 @@ within the source repo:
| 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` |
| Prototype files | `03-prototype/` | `/prototype` or `/import` |
| Prototype notes | `03-prototype/prototype-notes.md` | `/prototype` or `/import` |
| Evaluation report | `04-evaluation.md` | `/evaluate` |
| Raw evaluator files | `04-eval-raw/` | `/evaluate`, `/prototype` |
| Implementation handoff | `05-handoff.md` | `/handoff` |
| History snapshots | `history/` | `/ingest`, `/research`, `/prototype`, `/evaluate` |
| History snapshots | `history/` | `/ingest`, `/research`, `/prototype`, `/import`, `/evaluate` |
| Provenance log | `provenance.json` | `/handoff`, `/revise`, `/respond` |
| PR description | `06-pr-description.md` | `/publish` |
| Publish metadata | `publish-metadata.json` | `/publish` |
Expand Down Expand Up @@ -114,6 +121,10 @@ PRD-only:

Enriched:
/ingest [UX] story → reconcile prior work → [research] → prototype ⇄ evaluate → handoff → revise → publish → respond

Bring your own prototype:
/ingest [UX] story → import ⇄ evaluate → handoff → revise → publish → respond
→ fixes happen at the prototype's source, then /import again
```

Research is conditional in either flow. Feature-only and PRD-only prototypes
Expand All @@ -131,8 +142,19 @@ prototype and evaluation have been reviewed against that context.
- 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.
- Initial `/ingest` completed and the researcher says the team already has a
prototype → recommend `/import` instead of `/research` or `/prototype`
- `/research` completed → recommend `/prototype` to explore design directions
- `/prototype` completed → recommend `/evaluate` (always — never skip evaluation)
- `/import` completed with gaps the researcher wants to close → recommend
updating the prototype at its source and running `/import` again
- `/import` accepted by the researcher → recommend `/evaluate` (always — never
skip evaluation)
- Any `/evaluate` outcome below that recommends `/prototype` for an imported
prototype (`Prototype mode: imported`) → recommend fixing the selected
findings at the prototype's source and running `/import` again instead.
Do not run `/prototype` against an imported prototype unless the researcher
asks to replace it with a generated one
- `/evaluate` Pending or Confirmed with valid finite authorized fixes (non-empty IDs from the current saved assessment, bound to current prototype iteration, discovery revision, and context revision) → recommend `/prototype` to address authorized findings; this is a requested repair loop, not phase completion — Confirmed status and severity endorsement are preserved. Stale bindings (changed prototype, discovery, or context since the assessment) require a current `/evaluate` instead. Pending without valid authorization → stay in evaluation review; severity endorsement alone is not fix permission
- `/evaluate` Confirmed with explicit `Authorized fixes: None` and `Ready for handoff: Yes` (no critical issues, no outstanding repairs, enriched context, current bindings) → recommend `/handoff`; missing or unknown `Authorized fixes` is not `None`; missing or unknown `Ready for handoff` is not `Yes`
- `/evaluate` Confirmed with `Authorized fixes: None` but `Ready for handoff` is No or unknown → stay in evaluation/iteration review; do not recommend `/handoff` when the saved readiness assessment does not support it
Expand Down Expand Up @@ -177,6 +199,8 @@ user needs, recommend `/prototype` directly.

- `/research` is always skippable — go directly to `/prototype` if the
researcher has sufficient domain knowledge or existing research data
- `/prototype` is skippable when the team already built the prototype — use
`/import` to bring it in
- 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

Expand All @@ -189,7 +213,8 @@ Researchers can enter at any phase if they bring the prerequisite artifact:
| `/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` |
| `/import` | `00-context.md` and `01-discovery.md`; a prototype that meets the accepted-input requirements in `import.md` (files, a way to view them, and feature scope). Proceeding to `/handoff` also needs an enriched context |
| `/evaluate` | Active prototype (from `/prototype` or `/import`) 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` |
Expand Down
38 changes: 33 additions & 5 deletions ux-design/skills/evaluate.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,15 @@ required skill is unavailable, stop and ask the researcher to run `./install.sh`

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.
`/prototype` first, or `/import` when the prototype was built outside this
workflow.

When `Prototype mode` is `imported`, recompute the fingerprint of
`03-prototype/code/` using the procedure and recorded `Fingerprint
exclusions` from `import.md` § Step 2, and confirm it matches the recorded
`Prototype fingerprint`. When a `Git commit` is also recorded, check it as a
secondary record. If the fingerprint does not match, stop and recommend
`/import` again. Do not evaluate changed files under an old import record.

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,
Expand Down Expand Up @@ -86,10 +94,20 @@ 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
directions. For an imported prototype, view `03-prototype/code/` with the
`Viewing method` recorded in `prototype-notes.md`, or use the `Hosted URL`
only when it is recorded as verified against the snapshot. Scope the
evaluation to the recorded `Scope`. The import's screenshots under
`03-prototype/screenshots/` can be reused; capture any states they miss. If
serving is not possible, capture screenshots of the important
screens and states into
`.artifacts/ux-design/{issue-key}/04-eval-raw/screenshots/`.

When `prototype-notes.md` records `Prototype limits` (for example, mock
data, stubbed authentication, or simplified permissions), pass them to each
evaluator as context. Findings that depend on real data or real permissions
are limited by those limits; say so instead of reporting them as verified.

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.
Expand Down Expand Up @@ -152,11 +170,17 @@ each run:
`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.
For an imported prototype, `/import` writes `rfe-snapshot.md` from the
ingested story. If it is absent, stop and recommend `/import` again; do
not write a snapshot here.
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.
needs the prototype ID for its native artifact path. For an imported
prototype, the ID is `N/A — imported`; skip the refinement-input copy in
item 6 because the upstream create skill does not refine imported
prototypes.
5. Run the evaluator from the run directory with `{story-key}`, prototype URL,
`--no-fix`, and `--workspace=<path>` when a workspace clone exists:

Expand Down Expand Up @@ -324,8 +348,10 @@ updates `Authorized fixes` without resetting the Confirmed status — the
endorsed severity and finding dispositions stand.

After fix authorization, recommend `/prototype` to address the authorized
findings. The revised prototype requires a new evaluation before handoff;
the prior authorization does not carry forward to the new iteration.
findings. For an imported prototype, recommend that the researcher make the
authorized fixes at the prototype's source and run `/import` again; list the authorized finding IDs so they can be traced. The revised
prototype requires a new evaluation before handoff; the prior authorization
does not carry forward to the new iteration.

#### Run-ID and Path Safety for Full Evaluation Artifacts

Expand Down Expand Up @@ -398,6 +424,8 @@ Omit sections for methods that did not run. Use this structure:
**Date:** {date}
**Evaluation revision:** {revision number}
**Prototype iteration:** {N}
**Prototype fingerprint:** {recorded fingerprint for an imported prototype, or "N/A"}
**Prototype Git commit:** {recorded SHA when the import came from Git, or "N/A"}
**Discovery revision:** {revision evaluated}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After decoupling, this becomes something like **Prototype fingerprint:** {content hash} with the SHA recorded as a separate optional field when available. The commit alone can't identify non-Git imports.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. **Prototype fingerprint:** plus an optional **Prototype Git commit:**.

**Context revision:** {from 00-context.md at assessment time}
**Depth:** {Quick / Standard / Full}
Expand Down
Loading