---
title: "Collect agent friction"
description: "Let agents report the docs, setup and tooling gaps that cost them time, and see which ones keep coming back."
---

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

# Collect agent friction

Agents run into the same papercuts again and again: a doc that misses a step,
an error that points the wrong way, an install that needs a token nobody
mentioned. Friction reports collect them. Every report of the same problem
adds to one item, so the count shows what to fix first.

Friction reports are in early access: ask us to turn on `friction` for your
workspace.

## What a report contains

| Field | What goes in it |
| --- | --- |
| `scope` | `repo` for the code, docs, scripts or config of the repository; `environment` for setup, secrets, services and installs; `trevize` when a Trevize tool or step got in the way |
| `title` | A short imperative summary, 8-120 characters |
| `whatHappened` | What happened, with the error or output |
| `wanted` | What was expected or needed instead |
| `reproduction` | The steps or exact command that reproduce it |
| `cost` | `minutes`, `retries` and/or a `note` |
| `investigation` | Optional preliminary cause |
| `relevantFiles` | Optional repo-relative paths |
| `tool`, `stepName` | Optional tool or command, and blueprint step |
| `agent` | Optional `harness`, `model` and `effort` of the reporting agent. Cloud runs fill in the harness and model themselves |

Never put secrets or customer data in a report.

## What gets recorded

The server checks every report before recording it, whichever way it was
filed. A report is skipped, with a hint for improving it, when:

- the reproduction is missing or shorter than 20 characters,
- it only describes the reporting session ("I forgot", "my context") and
  names no tool, file or cause,
- `wanted` restates `whatHappened`, or no cost is given,
- a `repo` report names nothing in the repository, or a `trevize` report
  names no tool or step.

A skip is guidance, not an error: the agent improves the report and files it
again.

Reports are matched by scope, repository and title. Titles are compared after
removing case, punctuation, numbers, commit SHAs, paths and filler words, so
"Typecheck fails at 3f9a2c1" and "typecheck fails at 9b8e7d6" are the same
item. A matching report adds one to the item's count and keeps its details.
Each item keeps its 50 most recent reports; the count keeps going up after
that.

An item is `open` until someone resolves or dismisses it. A new report of a
resolved or dismissed problem opens a new item, so a regression shows up.

## Filing reports

In cloud runs and sessions, agents get a `file_friction` tool and are asked
to use it before they finish a step. Each call stays visible in the run's
timeline.

Locally, use the CLI or its MCP server:

```bash
trevize friction file \
  --scope environment \
  --title "bun install needs the registry token" \
  --what "bun install exits with 401 from npm.pkg.github.com" \
  --wanted "The token documented in the README" \
  --repro "Run bun install in a fresh clone without NPM_TOKEN" \
  --minutes 15
```

`--json <file|->` reads the whole report as JSON, and `--dry-run` runs the
check locally without sending anything. The repository defaults to the
`origin` remote. `trevize mcp` exposes the same as the `file_friction` tool.

To teach local agents when and how to file, install the `file-friction` skill
into the repository:

```bash
trevize skills add file-friction
```

It writes `.agents/skills/file-friction/SKILL.md`, the shared skills folder
that works across agents. For an agent that only reads its own folder, pick it
with `--dir`, for example `--dir .claude/skills`. `trevize skills add` with no
name installs every Trevize skill. An existing skill is kept unless you
confirm overwriting it; pass `--yes` to overwrite without asking.

## Reviewing items

The **Friction** page in the web app lists the workspace's items, most
reported first, with a two-week trend for each. Switch between active,
resolved and dismissed items, and filter by status, scope or repository. An
item shows its latest report, the average time and retries it costs per
report, and its recent reports with the runs they came from and the harness,
model and effort of the agent that filed each one.

From an item you can:

- **Fix with agent**: start a background task on the item's repository with
  the workspace's bug fix blueprint and the report as its prompt. The item
  moves to `fixing` and links to the task.
- **Create Linear issue**, when an issue tracker is set up. The item moves to
  `routed` and links to the issue by its key.
- **Resolve** or **Dismiss** it. Dismissing needs a reason.
- **Reopen** a resolved or dismissed item. If a newer active item already
  collects the same reports, reopening is refused.

From the command line:

```bash
trevize friction list --status open --scope repo
trevize friction get <id>
trevize friction dismiss <id> --reason "Works as intended"
trevize friction issue <id>
```

The `/api/v1/friction` routes do the same: `POST /friction` files a report,
`GET /friction` lists items most reported first, `GET /friction/{id}` returns
an item with its recent reports, and `POST /friction/{id}/status` resolves,
dismisses or reopens one.

## Fixing automatically

An [automation](/guides/automations) with the **Friction reports** trigger
fixes items on its own: when an open or routed item in one of its repositories
reaches the number of reports you set, it starts a run on that repository with
the item's report and moves the item to **Fixing**.

## Issue tracker

Workspace owners and admins can send friction items to Linear under
**Settings → Friction**. Issue creation is off until a tracker is picked, and
Linear is offered once the workspace has connected it under
**Settings → Integrations**.

- **Default team** gets every issue, unless **Teams per repository** maps the
  item's repository to another team. A **Project** is optional.
- Every issue gets the `friction` label, created on the team if it doesn't
  exist. The issue carries the report, its scope, repository and report
  count.
- **Create issues automatically** creates an issue when an open item reaches
  the set number of reports, for the scopes you pick. Trevize-scope items are
  never sent automatically.
- When an item with an issue is reported again, the issue gets a "seen again"
  comment, at most once a day.
- When the issue is completed in Linear the item is resolved, when it is
  canceled the item is dismissed, and when it is reopened the item goes back
  to `routed`. This needs **Issues** events enabled on the Linear app's
  webhook.

`GET /friction/settings` and `PUT /friction/settings` read and change these
settings (`PUT` is for owners and admins), and `POST /friction/{id}/issue`
creates one item's issue.

Source: https://docs.trevize.dev/guides/friction/index.mdx