friction_log v1.0.0

name: "friction_log" description: "Run a disciplined UX friction-logging practice: capture user friction signals with concrete evidence, score severity on the standard 0-4 rubric, and route them into a prioritized fix queue. Triggers when an agent needs to collect, triage, or report usability friction, audit a flow for pain points, or turn support tickets and session notes into ranked fix tickets."

Friction Log

Purpose

Give an agent a repeatable practice for handling UX friction: capture every signal with evidence instead of impressions, score it honestly, and turn the stack into a fix queue a team can actually work. One entry per signal. Evidence first, opinion last.

Workflow

1. Capture

Write one entry per friction signal using assets/templates/friction-entry.md. A signal is one concrete, observable thing: a rage-click cluster on the checkout button, three identical support tickets about the same step, a tester who could not finish a task. Record:

• where it happened (exact screen/route, device, date),
• what was observed (exact copy, exact click counts, exact error text),
• which signal type from references/signal-catalog.md it is,
• who was affected and what the task was.

A feeling is not evidence. "Users seem confused" stays out until it is backed by a count, a quote, or a session.

2. Classify

Tag each entry as one of three classes:

• Behavioral - caught by analytics or session tools (rage clicks, dead clicks, u-turns, form abandonment). See the signal catalog for strict detection thresholds.
• Reported - came from a person (support ticket, CES survey comment, user interview note).
• Observed - found in a usability session or expert walkthrough (task failure, hesitation, error).

3. Score severity

Apply the 0-4 severity rubric in references/severity-rubric.md. Weigh three factors: frequency (how common), impact (how hard to overcome), persistence (one-time or recurring). Score severity, not priority. A rare blocker can outrank a common annoyance. When frequency is unknown, say so and score on impact; never invent a frequency to make the math cleaner.

4. Prioritize

Score the four routing dimensions, 1-5 each:

• Reach: how many users hit it,
• Severity: your 0-4 score, converted to 1-5 (add 1),
• Value proximity: how close it sits to the user's moment of value,
• Confidence: how much the evidence agrees (recordings, data, and reports pointing the same way).

Priority = reach x severity x value proximity x confidence. The number is a triage aid, not a measurement of the universe. It exists to make assumptions explicit so the loudest stakeholder does not set the queue. Maintain the log as a JSON file (schema in bin/friction_rank.py) and run the ranker to get the ordered list with quick-win flags: python3 bin/friction_rank.py log.json. A worked example of an entry plus its ranker output is in assets/worked-example.md.

5. Route to a fix

Turn the top entries into fix tickets using assets/templates/friction-report.md. Each ticket carries: the evidence, the severity, the priority score, and a proposed fix marked either measured (you checked the real data) or hypothesis (you did not). A proposed fix with no number behind it is a guess; label it one.

6. Close the loop

When a fix ships, record what changed, how you re-measured, and the new reading. Status markers: open, partial, fixed. A friction log with no closed entries is a graveyard, not a practice.

Output Contract

• Friction log: one numbered entry per signal, each with location, evidence, signal class and type, severity 0-4, and status.
• Fix queue: entries ranked by priority score, top items converted to fix tickets with evidence links and proposed fixes labeled measured or hypothesis.
• Report: a dated summary showing what was found, what was fixed, and what moved the metrics.

Operating Rules

1. Every factual claim gets evidence or gets cut. No invented numbers, dates, or quotes.
2. Severity and priority are separate jobs. Severity describes the problem; priority is the owner's decision.
3. Capture before you diagnose. Write down what happened before writing why you think it happened.
4. One entry per signal. Do not bundle five different stumbles into one "checkout is confusing" entry.
5. Scope each entry: who it hits and whether it blocks the critical task or just slows a side path.
6. Fix-the-system beats fix-the-instance: a broken pattern everywhere outranks one broken screen.
7. Measure before proposing. Check the real data, then propose.
8. Keep the log alive: review open entries on a schedule, retire stale ones with a note, never silently.