# Find and fix frictions - Obss

Use cases
Find and fix frictions
Rank the frictions that agents hit, read their evidence in the traces, hand one to an issue or an AI assistant, and confirm the fix.
A
friction
is a problem that agents hit, tracked across runs and experiments. Find the one that stops the most runs, hand it to whoever can fix it, and launch again to confirm the fix.
Prerequisites
Finished experiments with
Insights
on, because most frictions come from Insights. If an experiment ran with Insights off, select
Run insights
on it first.
Access to the place where the fix goes: your product, your tool, your custom agent, or the task.
Steps
1
Open the friction list
Open
Analyze → All frictions
for the whole project, or the
Frictions
tab of an experiment, task, tool, treatment, machine, agent, or schedule. To start from a difference instead, open the experiment’s
Comparisons
tab: its
Brief
lists the frictions seen with the side that did worse.
2
Filter by where you can fix it
Fix
Machine
or
Task quality
frictions first, because they make the other results unreliable. Then, under
Where to fix
, choose where you can act:
Product
,
Custom agent
(shown when your custom agent has frictions here),
Setup
, or
Agent behavior
, and narrow the list with
Family
and
Recovery
. The list starts sorted by
Unrecovered runs
, so problems that agents never got past come first.
3
Read the top friction
Select the top friction to see
What goes wrong
,
Why it matters
, and the
Suggested fix
with where to make it. When the agent also contributed,
What the agent did
follows the fix.
Where it happens most
,
Rate by treatment
, and
Rate by agent
show whether some agents or treatments avoid it.
4
Read the traces at the cited steps
Under
Recent evidence
, each run shows what happened, with quotes from its trace. Select the step link to open the run’s
Traces
at the first step that the friction cites, and read the steps around it to confirm the cause. The
Runs
section lists every run with the friction.
5
Copy it as Markdown
Select
Copy as Markdown
to copy where to fix the friction, what goes wrong, the suggested fix, where it happens most, three recent runs with links to their traces, and the friction’s
frc_
ID. Paste it into an issue, or give it to the AI assistant that you use in your product’s or your custom agent’s repository. Copying doesn’t change anything in Obss.
6
Fix it in the right place
Where to fix
What you change
Product
A tool in the treatment (MCP server, CLI, SDK, or skill), or your product’s API, errors, or docs
Custom agent
Your own custom agent: its instructions, tools, or code
Setup
The treatment’s tools, the task’s text or checks, or the machine
Agent behavior
Nothing in your product or setup. Try an agent or treatment that avoids the friction.
Where it happens most
shows which ones do.
7
Launch again and confirm
Open the experiment where the friction occurred and select
Launch again
. When it finishes, open the friction from the new experiment’s
Frictions
tab. If the fix worked, the friction has fewer runs, or it no longer appears for that experiment.
Interpret the results
A fix worked when the friction has fewer runs in the new experiment and more trials pass on its
Matrix
. Frictions keep their IDs across experiments, so you can follow one over time.
What you see
What to do
The friction appears at the same rate
The fix didn’t reach the cause. Read the new runs’ traces at the cited steps.
The friction is gone, but the pass rate didn’t move
Another friction now stops the agent. Rank the list again.
A new friction appears
The fix changed the agent’s path. Open it and read its evidence.
From the CLI and the plugin
An AI assistant with the
Obss Plugin
or the
CLI
can do this whole guide in your repository. When it reads a friction, it gets the same fields as
Copy as Markdown
.
Step
CLI
Plugin (MCP)
Rank the frictions
obss frictions list
list_frictions
Read one friction
obss frictions get
get_friction
List its runs
obss runs list --friction-id
list_runs
Read a run’s steps
obss runs trajectory
get_run_trajectory
Launch again
obss experiments rerun
rerun_experiment
For example, list the unrecovered product frictions, then read one friction’s counts in the new experiment:
obss
frictions
list
--fix-in
product
--recovery
unrecovered
obss
frictions
get
frc_7d20e6b4
--experiment-id
exp_c41d08f2
Or ask your AI assistant:
Read the top unrecovered product friction in Obss, open the steps its runs cite, and fix the cause in this repository. Then launch the experiment again and tell me whether the friction's runs went down.
Other ways to run it
Fix one tool.
Open the tool under
Manage → Tools
and select its
Frictions
tab to see the frictions of every run that used it.
Fix your
custom agent
.
Choose
Custom agent
under
Where to fix
.
Use Ask Obss.
Ask Obss
can explain a friction and compare it with the code in a public GitHub repository.
Make sure it stays fixed.
Schedule the experiment to catch the friction if it returns. See
Track results over time
.
Next steps
Frictions
Read where to fix each friction and why it happens.
Run details
Read a run’s steps, profile, and output.
Track results over time
Catch a friction when it comes back.
Install the Obss Plugin
Fix frictions from your AI assistant.
Track results over time
Ask Obss as a custom agent
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform