Find the task behind the screen
Map decisions, interruptions, errors, recovery and completion instead of beginning with a visual redesign.
Skill
UX Ergonomics
Make the next step easier to understand and do.
An evidence-led UX skill for workflows and human-agent interactions. Trace the real task, find where people can lose their way and turn findings into changes you can verify.
Fictional finding: failed import discards mappings Observation: inputs disappear after the error Consequence: task must restart from scratch Change: preserve mappings; explain retry and cancellation Acceptance: keyboard user can inspect and retry without re-entry Evidence gap: affected-user task observation pending
Fictional worked example. It illustrates the intended output; it is not a measured result or a real customer story.
Make authority understandable
Show who decides, who acts, what can be stopped and what evidence confirms completion.
Give recommendations a fair test
Separate observation from inference and specify what would pass or fail each consequential change.
The film
Forty fields. Then it's gone.
In 68 seconds, Pat maps forty columns and loses them all to one failed import. UX Ergonomics rides the real route to the stop where it breaks, keeps the work, says what retry will do, gives a way out and checks it with only a keyboard. It will not call the fix better until real people try it. Captions are on the player; a transcript is below.
Read the transcript
Forty fields. Twenty minutes. Perfectly mapped.
Import failed. Everything’s gone.
People don’t quit at the hard part. They quit when their work disappears.
And no, a sparklier retry button won’t save it.
UX Ergonomics rides the real route, right through the stop where it breaks.
The fix: keep the mappings. Say what retry will do. Give a way out.
Then test it with only a keyboard: Tab, Tab, Enter. Nothing typed twice.
Is it better? Ask real people. Until then, it won’t say so.
On screen: Don’t throw away their work.
UX Ergonomics. Make the next step easier to understand and do.
Pat, the import and the form are a fictional example. The film shows how the skill behaves; it does not report results.
See the work take shape.
Fictional worked example. It illustrates the intended output; it is not a measured result or a real customer story.
Frame and inspect
Name the actor and task, gather relevant evidence and walk both normal and failure states.
Recommend a concrete change
Choose the lenses that fit: cognition, accessibility, authority, recovery and visual craft.
Verify at the right level
Check keyboard and runtime behavior, then use affected-user tasks where the claim needs them.
Fictional example
A recovery button is not recovery evidence
The brief A fictional analyst cannot recover a failed batch without re-entering every field.
Before
Add an animated retry button and call the workflow accessible and faster.
After applying the method
Walk the failure state, preserve user input, expose what retry will do, provide cancellation, and define a keyboard and task-completion check before claiming improvement.
Visual polish can support the task, but it cannot establish usability or conformance.
A clear job.
A useful stopping point.
Use when task completion, cognitive load, accessibility, authority, error recovery, or longitudinal impact needs investigation.
Use it when
- People cannot tell what happened or what to do next.
- A workflow loses input or hides recovery after an error.
- An agent interface makes approval, cancellation or completion unclear.
Choose another route when
- An accessibility-conformance certificate based on a source scan.
- Treating anecdotes as prevalence or a visual preference as measured usability.
Frame and gather
The product surface is known but the actual breakdown is unclear.
A task model, claim-level evidence map, and ranked uncertainties.
Review and recommend
An inspectable flow needs changes.
Mechanism-specific findings, authority choices, and observable acceptance criteria.
Verify
A decision package needs an adversarial check or study.
A bounded verdict, valid study plan, and explicit inference limits.
Read the canonical method
UX Ergonomics
Make the task easier to complete, and show what evidence would prove the change helped.
Frame the job, then inspect the surface
Start with task analysis: actor, trigger, desired outcome, context, frequency, expertise, prerequisites, decisions, actions, feedback, interruptions, handoffs, failures, recovery, and completion evidence. Keep nominal flow and exceptions. Do not redesign while still determining the task.
Use evidence synthesis and the evidence ladder to separate direct product behavior, research, standards, inspection, and anecdotes. Record source population, method, setting, date, applicability, contradictions, and uncertainty. Source count is not strength; do not derive prevalence from complaints or social posts.
Review through the relevant lenses
For discoverability, action, feedback, and learning use cognitive walkthrough. State assumed knowledge and distinguish predicted breakdown from observed behavior. For accessibility use layered evaluation: automation, source semantics, keyboard/focus/reflow/motion/timing/error behavior, assistive technology, cognitive access, and affected-user tasks as warranted. A subset cannot establish full conformance.
For agents use authority mapping: information visibility, decision/execution owner, consequence, uncertainty, reversibility, preview/approval/intervention/undo/retry/escalation, completion evidence, and memory/deletion control. Scale friction to the actual risk and existing grant, not a blanket request for confirmation. Consider longitudinal, organizational, and adversarial effects using the retained deeper contexts.
Recommend a falsifiable change
For each consequential finding separate observation, inference, recommendation, and requirement. Name the mechanism, affected task/state, consequence, evidence level, alternatives, uncertainty, and acceptance criterion. Use acceptance criteria; add a numeric threshold only with a baseline, risk, requirement, or decision-power reason. State the method and evidence that would fail the recommendation.
The credited visual craft material preserves distinct source roles and does not require an install. Use it only to serve the task and preserve the author's intentional choices; do not convert a design preference into a measured usability claim.
Verify and learn
Apply adversarial verification, returning pass/revise/blocked with material gaps. Use study design for the lightest valid empirical check: population/variation, tasks/states/environment, behavior measures, assistance/critical errors/abandonment, moderation/counterbalance/access, analysis, stop rule, and generalization bounds. Small formative studies can expose breakdowns; they do not estimate prevalence. Questionnaires supplement behavior.
Return a task-and-evidence map, prioritized findings, authority decisions, concrete changes, acceptance criteria, validation status, and unresolved evidence. An uncalibrated weighted rubric or a structural test is not observed benefit.
Limits and prerequisites
- Expert inspection is not observed-user evidence; anecdotes cannot establish prevalence.
- Accessibility conformance needs adequate runtime/manual evidence at the stated scope.
- Visual Taste guidance is an optional craft lens; it never outranks task evidence, usability, or user voice.
Your first useful run.
Bring one user task, an inspectable flow and the breakdown you want to understand.
The download contains the complete skill folder. Extract it into the skills directory supported by your agent, keeping its references and license together. Or use the source installer below. Python 3.11+ is required for that installer.
Start from the public source
git clone https://github.com/michaeljabbour/amplifier-skill-ux-ergonomics.git
cd amplifier-skill-ux-ergonomicspython3 scripts/capability.py doctor
python3 scripts/capability.py install --dest ~/.agents/skillsNative tools and optional execution
amplifier bundle add ./bundle.mdThese commands are for the optional native surface. Follow its installation guide and prerequisites; portable method installation is separate.
Keep the complete skill folder together, including its references and license. The host applies the method in your context; the skill does not start a background service.
- Requires Git and Python 3.11+ for the repository installer. The portable method itself can be read by a compatible agent without a service or provider account.
- The destination is a skills-parent folder. Use the discovery path supported by your agent; ~/.agents/skills is an example, not a universal host setting.
- Keep the complete installed folder, references and license together. Identical reinstall is safe; conflicts are refused. A deliberate --replace keeps a dated backup.
Try this with your agent
Use UX Ergonomics to review this fictional batch-import failure flow. The analyst loses entered mappings after an error. Separate observation, inference and recommendation; propose recovery behavior and keyboard/task checks without claiming a measured improvement.Use after installing in a host that loads skill folders. Supply your own task files and review the result.
Keep the guide nearby
Read the guide · License · Changes · Release metadata · Install guide · Migration · Validation · Native guide · NATIVE INSTALL · consolidation · OPTIONAL CRAFT ADAPTERS
Know what you can rely on.
Native bundle structure, references and portable installation are checked. No usability study or accessibility-conformance claim is established by those structural checks; each product needs validation on its actual tasks and surfaces.
Read the checks and their scope
- Native bundle and mode references — passed
4 agents, 6 recipes, 6 modes, one canonical skill, 50 namespaced mentions. Method/shape conformance only; no usability study or accessibility-conformance claim.
- Portable packaging and install — passed
All operations passed. No runtime activation or effectiveness measured.
- Skill discovery metadata — passed
Skill is valid. This is a structural check, not a behavioral benchmark.
Native bundle structure, references and portable installation are checked. No usability study or accessibility-conformance claim is established by those structural checks; each product needs validation on its actual tasks and surfaces.
Fictional examples explain the capability. Tests check the stated behavior. Outside-user outcomes need their own evidence.