| name | ux-interaction-map |
| description | Map the interaction structure of an application, website, or product flow. Use when Codex needs to inspect a product surface, enumerate screens or states, build a route or page manifest, map the main user flows for important tasks, identify decision points, loops, dead ends, and hidden branches, and report how the interaction model actually works before deeper usability evaluation or redesign work. |
UX Interaction Map
Overview
Inspect a product surface and turn it into an auditable interaction model. Start by writing a mapping plan, define the product boundary and target tasks, inspect the surface structure, build a screen or state manifest, walk the important flows, then report the interaction graph with key branch points, loops, dead ends, and open questions.
This skill is not a general usability critique and not a wireframing exercise. The main job is to produce a faithful map of how the product is structured and how users move through it.
Workflow
- Write the mapping plan before exploring deeply.
- Record the product, surface boundary, target tasks, platforms, auth assumptions, and desired deliverable.
- Decide whether the goal is broad surface mapping, task-specific flow mapping, or pre-audit groundwork.
- Read interaction-plan.md and use its template.
- Lock the surface boundary and task set.
- Define what is in scope: marketing pages, signed-in app, checkout flow, settings, support flows, and so on.
- Freeze the target tasks before broad exploration so the mapping does not drift.
- If the product has gated areas, note what access you have and what remains out of scope.
- Inspect the product structure before choosing tooling.
- Use the browser first to understand routing, navigation patterns, menus, modals, drawers, and page-state changes.
- Identify whether the surface is small enough to map manually or large enough that you need a crawler or scripted collector.
- Read surface-inventory.md.
- Build the surface manifest before drawing conclusions.
- Create a manifest artifact in the task workspace. Use CSV or JSON for large surfaces; use Markdown only for very small ones.
- Give each route, screen, or important state a stable row and identifier.
- Record enough metadata to revisit the same surface later.
- Reconcile the manifest against the observed surface before focusing on flow quality.
- Walk and map the important tasks.
- Trace the user path for each target task from entry to completion, drop-off, or error state.
- Record branch points, optional paths, loops, dead ends, and recovery paths.
- Read flow-mapping.md.
- Analyze the interaction structure before moving to evaluation.
- Identify navigation depth, repeated patterns, state changes, hidden dependencies, and places where the user must make decisions.
- Record interaction friction as structure observations, not yet as usability verdicts.
- Read structure-and-friction.md.
- Use sub-agents only after the surface manifest exists.
- Keep scope definition, deduplication, merge, and final synthesis with the main agent.
- Delegate disjoint task flows, source sections, or screen batches with fixed output fields.
- Require one structured result per assigned manifest row or task path.
- Read subagent-protocol.md.
- Report the map as a reusable artifact.
- Return the surface boundary, manifest summary, mapped tasks, interaction graph, friction observations, and unresolved areas.
- Make the output usable by later
ux-usability-audit or ux-competitive-benchmark work.
- Read reporting-schema.md.
Operating Rules
- Treat scope as a contract. If the mapped surface changes, state the change.
- Inspect first, then automate. Do not write a crawler before you understand the product structure.
- Use scripts to enumerate routes or states when the surface is too large to cover confidently by hand.
- When interactive browser exploration settles into a repeatable mapping path, save the final automation code in the task workspace and record how to rerun it.
- Do not confuse structural mapping with usability judgment; keep those separate.
- Preserve evidence for each mapped screen or state so another pass can verify it.
- If coverage is partial because of login barriers, dynamic state, or crawl failures, say so explicitly.
Read These References When Needed
