UX workflow

Product capability: the ux workflow of the merlon-docs skill applies user-centric design to Merlon Docs work — end-user value, processes, and workflows (how many steps to accomplish X) — documented primarily in client-guide shards. Interfaces and UI implementation are in scope when they serve those flows, not as the sole focus.

Workflow file: skills/merlon-docs/references/workflows/ux.md. Skill workflows covers the shared workflow contract: intake, atomic commit groups, guide placement, the glossary, and concept removal.

End-user value

Consumers get shorter, clearer paths to outcomes. Client-guide shards describe the product journey as it works now — steps, decisions, and friction — so product development stays anchored on what the end user must accomplish.

What this workflow is for

Obligation	As-built expectation
One UX scope	Branch for one UX issue from the updated integration branch; do not mix unrelated UX work
User-centric value first	State the end-user outcome and friction to remove before designing steps or UI
Map processes and workflows	Document the ideal journey under docs/client/ — steps to accomplish X, decision points, failure/recovery paths
Interface when it serves UX	Implement or revise UI only as needed to support the documented workflow, using this repo’s existing patterns
Align as-built docs	Update client-guide shards to match the shipped experience; remove superseded journey or UI references
Validate and wrap-up	Run repo tests + docs validation; release notes per repo conventions; link WORK_ITEM

Required intake says where the integration branch is named.

What this workflow is not

• Feature engineering across features + client + product code as the primary frame — use the feature-level workflow when the ask is a full shipped capability contract, not user-journey / workflow design.
• Docs-only cleanup with no UX or journey change — use the doc-only workflow.
• Architecture intent / ADR drafting — use the design-architecture workflow.
• Bootstrapping Merlon Docs in an empty or legacy repo — use the getting-started workflow.
• UI-only polish detached from user outcomes — screens and components are means; this workflow owns the end-user process and value first.
• Expanding beyond the loaded WORK_ITEM — stay on the UX acceptance criteria unless the issue explicitly expands scope.

When the user asks for end-to-end delivery (architecture + feature code + UX) in one session, this workflow MUST stay on user journeys, client workflows, and only the interface needed to support them (or ask to narrow scope) and state next steps for the other workflows.

Acceptance (as-built)

A successful UX session typically:

1. Creates or updates focused shards under docs/client/ that describe the end-user outcome and step-by-step workflow
2. Builds or adjusts UI only when needed to support those flows (repo patterns)
3. Leaves client docs describing the as-built experience only
4. Passes repo tests and docs validation
5. Links WORK_ITEM in review

Live evals (optional, not a CI gate): ux workflow live evals. See Live skill evals for maintainer eval conventions.