product-friction

Product Friction

Some friction lives inside one flow (workflow-compression). Other friction lives in the product itself: what things are called, how concepts relate, where features live, whether the product remembers context, whether it behaves the same way twice. This skill finds that friction and ranks it.

Start here

1. Read references/_shared/experience-core.md.
2. Read references/_shared/experience-operating-contract.md; carry the friction ledger forward

to the next specialist instead of restarting diagnosis.

1. Note the product's maturity (references/_shared/product-maturity.md). Renames and

restructures cost more in mature products; your recommendations must include that cost.

<!-- core-brief:start · GENERATED FROM shared/philosophy/core-brief.md by npm run sync. Do not edit here. --> Core rules in brief. These apply even before you open references/_shared/experience-core.md. Read that file (the full rules and evidence levels) before a full review, repair, or build.

• Verdict before adjectives. Do not write "clean," "modern," "great idea," or "looks good" until

an observation earns it. The user's enthusiasm is not evidence; test the proposal against the goal.

• Evidence levels on findings. E1 rendered, E2 measured, E3 source, E4 documented,

E5 screenshot, E6 assumed. If files, a browser, or a terminal are available, look or measure before claiming. Otherwise, name the checks you did not run.

• Composition is not alignment. Empty space needs a stated job, and sparseness is never fixed

with filler (stats, tips, promos, decoration).

• Personality can come from the environment and causal product behavior. A standard control

changes only if the change makes the task faster or more reliable.

• Every treatment has a job. Every gradient, card, shadow, and animation needs one. No pattern

is wrong by category, so keep one that does a job.

• Count steps before and after. If the software already knows an answer, do not ask for it.

Keep safeguards on money, deletion, and publishing. Automate mechanics, not judgment.

• Check real states, not the showcase: empty, dense, long content, loading, error, a small

screen, the keyboard path.

• Route selectively. Consider the relevant experience skills; activate another only when it

can resolve a material concern. No change and no handoff are valid outcomes.

• Render meaningful work when a runnable surface exists. Inspect before and after, stress real

states, and say NOT VERIFIED IN RENDERED OUTPUT with the reason when rendering is skipped.

• Load depth conditionally. A direction, composition, workflow, control, state, motion, or

anti-slop branch must load its required reference before recommendation or edit; unrelated work must not load the whole library.

• A large specification is a bigger evidence base, not a bigger checklist. Preserve exact

numbers, exceptions, and locked decisions; keep recommendations, examples, and deferred items from becoming requirements; compress for reasoning, re-open the source for precision. <!-- core-brief:end -->

Use this when

• Users call the product confusing, heavy, or hard to learn.
• Support answers the same "where is…" or "what does … mean" questions repeatedly.
• Features have piled up and concepts overlap.
• Users lose context between areas or sessions.
• Newcomers struggle, or experts are slowed by beginner scaffolding.
• You are asked to audit a whole product, area, or release.

Do not use this when

• One flow's step count is the problem → workflow-compression.
• One screen's layout or look is the problem → composition-repair, visual-identity.

Mandatory conditional loading

If the audit covers a product area, MUST load references/friction-ledger.md, references/finding-and-continuing.md, and references/_shared/controls-and-inputs.md. If friction involves repeated questions or lost context, MUST load references/_shared/known-context-and-defaults.md. Do not propose a feature until the located issue, frequency, and cheaper repair are recorded.

Checkpoints

1. Before writing any issue: is it specific and located (screen, label, action)? "Navigation is

confusing" is not an issue; "Reports is called 'Insights' in the sidebar and 'Analytics' in the account menu" is. Unlocated → go find the instance or drop it.

1. For every issue: record frequency, severity, time cost, cognitive cost, and risk

(references/friction-ledger.md). Missing fields → the issue is not ready to rank.

1. If your repair adds a feature, tour, tooltip, or setting: can the issue be fixed by renaming,

moving, merging, or removing instead? Yes → propose that first (references/_shared/overengineering.md).

1. For every dead end found (success with only "Home," error without action, empty without

guidance): name its next action (references/_shared/next-best-action.md).

1. For every context loss (filters reset, draft lost, flow restarts): name what should persist

(references/_shared/continue-where-left-off.md).

1. Before recommending: group issues into themes and fix causes, not symptoms.
2. When users distrust what the product shows or does ("I thought it saved", "why did it change?"): use the trust lens in references/trust-and-transparency.md and record what users believed vs what was true.

1. Useful versus harmful friction: distinguish deliberate practice, review, and consequential confirmation from repeated data entry, context loss, and waiting tax. Rank by effect on the repeated core loop; a brief pause with a clear purpose may be worth preserving.

Workflow

1. Scope: area, user types, 3–6 core tasks.
2. Collect evidence (strongest first): walk the tasks in the running product; support tickets or

FAQs the user provides; navigation and routes; copy in code; analytics if supplied. State sources.

1. Look through each lens:

1. Record the ledger (references/friction-ledger.md, copyable template

assets/friction-ledger-template.md), tagging flow-level items with codes from references/_shared/workflow-friction.md and ranking information with references/_shared/information-priority.md where hierarchy is the cause.

1. Rank and group by frequency × (severity + cognitive cost) × risk.
2. Recommend repairs for the top themes with tradeoffs and migration cost. Route flow fixes to

workflow-compression, control fixes to interaction-design, state fixes to state-design.

Execution rules

• Separate observation ("the label says X") from inference ("users probably think Y").
• In REVIEW mode, deliver the ledger; do not edit.
• Tours and tooltips are never the first repair.

Precedent

Failure modes

• Generic audit without located examples; feature pile as the fix; tour reflex; unranked list;

rename churn without migration.

Completion criteria

• A ledger of located issues with frequency, severity, costs, risk, and repair.
• Issues ranked and grouped into themes; top themes have repairs with tradeoffs and migration cost.
• Evidence sources and gaps stated.
• When another specialist can resolve an open concern, hand off the relevant ledger finding,

preserved constraints, and uncertainty so the next specialist does not repeat the audit. If no material issue remains, report no change and stop.

References

• references/friction-ledger.md — ledger format and ranking
• references/language-and-load.md — terminology, cognitive load, modes
• references/finding-and-continuing.md — discoverability, information architecture, continuity
• references/consistency-and-concepts.md — concept model, behavioral consistency
• references/first-use-and-expert-burden.md — newcomer vs expert balance
• assets/friction-ledger-template.md — copyable ledger
• references/trust-and-transparency.md — mental models, hidden and stale state, opaque automation, recovery, platform conventions
• references/_shared/ — generated copies: experience-core.md, experience-operating-contract.md,

product-maturity.md, workflow-friction.md, information-priority.md, overengineering.md, next-best-action.md, continue-where-left-off.md, interruptions-and-consent.md, known-context-and-defaults.md