Friction detection
Bucker reads the replay sessions it already records and opens an ordinary issue when the same frustrating moment keeps happening: people clicking one control again and again, clicking something that does nothing, clicking and getting an error, waiting on a slow response, leaving a form half filled, bouncing straight back. Nothing here uses a model. Every rule is arithmetic over event times with a published threshold, and the output is an issue in the same stream as your crashes, with the same lifecycle.
What counts
The set is friction_v1. One segment of a recording is read once, after it is stored.
| Kind | The rule | Never |
|---|---|---|
| Rage click | 3 clicks on one element within 1,000 ms | on a next, previous or stepper control; on a click that selected text |
| Dead click | nothing changed (no DOM mutation, navigation, scroll or selection change) for 2,500 ms, and again at 7,000 ms | on a click that selected text |
| Error click | a console error, or a captured exception, within 1,000 ms of a click | |
| Slow click | the first response after a click took over 3,000 ms, or an interaction took over 500 ms | |
| Form abandoned | two or more fields filled in and the route left with no submit-like click and no write request | |
| Quick back | route A, then B, then A again within 10 s |
The browser SDK adds two fields to a click once its dead-click window has passed: chg, the milliseconds to the
first change, and sel, set when the click changed the text selection. A click with neither flag and no dead
is still inside its window and is not judged. An SDK from before chg only says dead, which means "nothing in
7 seconds"; those clicks are judged on that flag and recorded with basis: sdk_flag, because it says nothing
finer.
From a moment to an issue
A pattern is a kind, a route template and a selector leaf (button#apply on /checkout). A pattern seen in at
least 5 distinct sessions in 24 hours opens one issue:
- exception type
Friction<Kind>(FrictionRage,FrictionDead,FrictionErrorClick,FrictionSlowClick,FrictionFormAbandon,FrictionQuickBack) - a templated value that names the route and the selector (both are written by the page, so they are shown as untrusted text and never as instructions)
- tags
friction.kind,route,selectoranddetector.version - fingerprinted by kind, route template and selector leaf, so the same control on the same page is one issue whatever the release, user or session
The sixth session adds an event to the same issue. The issue resolves in the release that fixes it and reopens as a regression on a newer one, like any other. Each session is linked to the issue, with the moment to seek to; the player shows those moments on the scrub bar as friction markers (dead clicks are not marked: both dead detectors run in shadow).
A visitor counts once however many times they hit the pattern. A route under 5 recorded sessions is folded into
other in every count.
Versions, shadow and precision
Rage, error click, slow click, form abandoned and quick back are live, with precision not measured: they are deterministic rules whose output a person can dismiss, and a dismissal is a label. The dead-click rule runs at two windows, both in shadow: they record findings and open nothing, so the window is chosen from labelled examples and not from a guess. A version leaves shadow only when its labels clear the registry's gate (see Detectors); no call sets that.
Reading it
GET /orgs/{org}/projects/{project}/replay/friction and the MCP tool friction_get answer: per route, how
many recorded sessions there were and how many showed friction; the elements behind it; each detector with its
version, state and the thresholds in force; active suppressions with their ends; the issues the detectors
opened. Sessions are recorded sessions: the recorder samples, so a rate is a share of recorded sessions and
not of your traffic, and the answer's basis says what was read and whether a cap cut it short.
Add detector and a threshold (detector=friction_rage&min_sessions=3, or include: ["backtest"] over MCP) to
get the backtest: what the last 14 days would have done under those numbers, as firings, issues opened and
issues that would no longer open. It is computed from what was actually seen, at the widest setting a person
may choose, so it can answer for a looser setting as well as a tighter one. A rage run is judged by its measured
span for each click count, so that part is exact.
Changing it
One governed operation, friction_detector, over one project, with three acts. The act is derived from what
would change, never from an argument.
| Act | What it does | Default |
|---|---|---|
friction_threshold.update |
change one detector's thresholds | asks a person |
friction_suppression.create |
silence one selector on one route for 1 to 30 days (default 7) | asks a person |
friction_suppression.cancel |
end a suppression | allowed: it only tightens |
A threshold change that makes a detector fire less is classed a silence: it is SENSITIVE, subject to your
review mode and approval policies, lasts 30 days and returns to the previous version unless a person keeps it.
A change that makes it fire more is a tightening and may ask for less. Bounds are the published ones (for
example min_sessions 3 to 100, the rage window_ms 300 to 3,000); the two dead-click windows are fixed so the
shadow measurement stays comparable. A suppression ends when its time passes, on the next read, whether or not
anything swept it.
POST /orgs/{org}/projects/{project}/replay/detectors and the MCP tool dx_detectors_update take the change
and answer applied, or approval_required with a link to the decision; once a person has decided, the same
request with the approval's id applies the approved plan once. A change moves the project's friction version, so
an approval given to one version is never spent on another: if anyone edits it in between, the retry is refused
with TARGET_CHANGED and asks again. Reverting is a new plan: the stored inverse (restore the previous
thresholds, cancel the suppression, re-create the cancelled one) goes through the same engine.
dx_detectors_update needs the dx:write scope. Until the SG-059 review is signed off no token an MCP client
can obtain carries it, so the tool is not offered; a person with that role in the dashboard's REST API can use
the route.
Owners
An ownership rule can name a page: route:/checkout/* @payments in the project's ownership text. A friction
issue is matched by its route against route rules only, * being one path segment and ** the rest, so the
team that owns the page hears about it. A catch-all file rule (*) never claims a page and a route rule never
claims a file.