> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

Triage the [frictions](https://docs.oqoqo.ai/evaluation/frictions.md) stopping the most runs, inspect the underlying trace evidence, ship the fix in your product or setup, and relaunch to verify improvement.

```mermaid theme={null}
flowchart LR
  F["1. Filter Where to fix"] --> E["2. Read trace evidence"] --> M["3. Fix in product<br/>or setup"] --> R["4. Launch again &<br/>confirm drop"]
```

## Prerequisites

* Finished experiments with [Insights](https://docs.oqoqo.ai/evaluation/insights.md) enabled (run **Run insights** on older experiments if needed).
* Access to edit your product, tool, custom agent, or task setup.

## Steps

**1. Open the friction list**

Open [**Analyze → All frictions**](https://docs.oqoqo.ai/evaluation/frictions.md) for project-wide issues, an experiment's **Frictions** tab, or the [Brief](https://docs.oqoqo.ai/evaluation/comparisons.md#brief) on **Comparisons**.

**2. Filter by where to fix**

Filter **Family** to **Machine** or **Task quality** (or **Where to fix** to **Setup**) and clear environment or rubric problems first so results stay reliable. Then filter **Where to fix** to **Product**, **Custom agent**, **Setup**, or **Agent behavior** (sorted by **Unrecovered runs** by default).

**3. Read the top friction and trace evidence**

Open the friction to inspect **What goes wrong**, **Why it matters**, and **Suggested fix**. Under **Recent evidence**, select a cited step link to open [**Traces**](https://docs.oqoqo.ai/evaluation/traces.md) right at the failure point.

**4. Copy as Markdown**

Select **Copy as Markdown** to copy the problem summary, suggested fix, concentration, three recent trace links, and `frc_` ID into an issue or your AI assistant.

**5. Apply the fix in the right layer**

| Where to fix | Where to make the change |
| - | - |
| **Product** | Your skill, MCP server, CLI, SDK, API, error messages, or docs |
| **Custom agent** | Your custom agent's instructions, tools, or harness |
| **Setup** | Treatment composition, task prompt/rubric, or machine setup |
| **Agent behavior** | Try an agent or treatment shown under **Where it happens most** to avoid it |

**6. Launch again and verify**

Select **Launch again** on the experiment (or **After a fix, run the N tasks that differed again** inside a Clear difference [Brief](https://docs.oqoqo.ai/evaluation/comparisons.md#brief)). Because frictions keep stable `frc_` IDs across experiments, check the new experiment's **Frictions** tab to verify that affected runs decreased.

## Interpret the results

| Outcome after relaunch | Meaning and next action |
| - | - |
| Same friction rate | Your fix didn't address the root cause—inspect new trace steps. |
| Friction disappeared, pass rate unchanged | A downstream friction is now blocking the agent—rank the list again. |
| A new friction appeared | The agent progressed further and hit the next bottleneck. |

## From the CLI and the plugin

| Step | CLI | Plugin (MCP) |
| - | - | - |
| Rank top product frictions | [`oqoqo frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list) | [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions) |
| Inspect friction details and evidence | [`oqoqo frictions get`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-get) | [`get_friction`](https://docs.oqoqo.ai/mcp-server/frictions#get_friction) |
| List all matching runs | [`oqoqo runs list --friction-id`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-list) | [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs) |
| Read cited trace steps | [`oqoqo runs trajectory`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-trajectory) | [`get_run_trajectory`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_trajectory) |
| Relaunch experiment | [`oqoqo experiments rerun`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-rerun) | [`rerun_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#rerun_experiment) |

Example prompt for your AI assistant:

```text theme={null}
Read the top unrecovered product friction in Oqoqo, 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

* **Track one tool:** open any tool under **Manage → Tools** and inspect its **Frictions** tab across all experiments.
* **Investigate with Ask Oqo:** ask [Ask Oqo](https://docs.oqoqo.ai/operate/ask-oqo.md) to cross-check a friction against a public GitHub repository.
* **Prevent regressions:** put the experiment on a [schedule](https://docs.oqoqo.ai/guides/track-agents-over-time.md) after fixing.

## Next steps

> [card] [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md)
>
> Understand Where to fix, Family, and concentration rules.

> [card] [Run details](https://docs.oqoqo.ai/evaluation/traces.md)
>
> Inspect timelines, transcripts, and changed files.

> [card] [Track results over time](https://docs.oqoqo.ai/guides/track-agents-over-time.md)
>
> Keep fixed frictions from returning.

> [card] [Install the Oqoqo Plugin](https://docs.oqoqo.ai/operate/plugin.md)
>
> Fix frictions directly from your AI assistant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.