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

> ## Agent Instructions
> For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents:
> - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md)
> - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md)
> - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md)
> - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md)
> - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md)
> - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md)
> For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md).

# How optimizations work

> Understand what an optimization is, how Gauge reruns sessions with your edits, and how to read the results before you ship a change.

An optimization tests whether a change to what agents read fixes a problem they hit. You start from a problem Gauge found in real sessions. Gauge edits copies of the pages, Skills, or CLI rules those sessions used, reruns the same sessions with the edits in place, and compares the new findings to the old ones.

Nothing deploys. An optimization gives you a diff, the evidence behind it, and a summary you apply through your usual review process.

This page explains the model. For the steps, see [Improve agent experience](https://docs.withgauge.com/agents/guides/improve-agent-experience.md) for friction, or [Improve agent preference](https://docs.withgauge.com/agents/guides/improve-agent-preference.md) for objections.

## When to use an optimization

Use an optimization when Gauge has already recorded sessions where agents hit the problem. Reruns keep everything else the same, so a change in the findings points to your edit.

Use a different workflow when:

* The change is already in a pull request. See [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md).
* You want to confirm a fix after you ship it. Run the eval or preference prompt again against the live product.

## The parts of an optimization

| Part | What it is |
| - | - |
| Subject | What you want to fix: an issue, one finding on one run, or a goal you describe in your own words. |
| Source sessions | The recorded sessions Gauge reruns. An issue brings its 12 most recent sessions. A finding brings its one run. |
| Tree | The set of files you changed. Each file is a page (`page:<url>`), a Skill (`skill:<name>`), or CLI rules (`cli:<package>`). |
| Launch | One rerun of some or all source sessions with the current tree. An optimization can have many launches. |
| Notes | The diagnosis, each edit and why, and what each launch showed. |
| Result | The final summary, the changed files, and the findings that resolved, returned, or were introduced. |

A **finding** is one problem in one session. An **issue** groups the same finding across many sessions. Friction issues come from [Agent Experience](https://docs.withgauge.com/agents/concepts/agent-experience.md). Objection issues come from [Agent Preference](https://docs.withgauge.com/agents/concepts/agent-preference.md).

An optimization that starts from a goal has no source sessions. Ask Gauge proposes up to 12 sessions where the goal shows up, and you confirm them before it edits anything. An optimization holds at most 12 sessions.

## How a rerun works

A launch reruns each source session with the same task or prompt, scenario, agent, model, and settings. The only difference is the tree:

* **Pages** in the tree replace the page the agent requests at that exact URL. Every other page serves what the source session saw.
* **Skills** in the tree replace or add to the Skills the session staged.
* **CLI rules** change what a command prints, add or replace options, or set environment variables. Agents see the change without a new CLI release.

Web search results do not change between the source session and the rerun.

URLs match exactly. An edit to `/pricing` does not cover `/pricing.md`, and an edit on `www.acme.dev` does not cover `acme.dev`. If a session reached the same content through several URLs, add each one to the tree.

You can rerun only the sessions your edits address. To try another edit, change the tree and launch again from the same optimization. You cannot start a new optimization from a rerun's findings.

## Read the results

Gauge analyzes each rerun as it would any session. It then sorts the findings into three groups:

| Outcome | Meaning |
| - | - |
| Resolved | A finding from the source session did not appear in its rerun. |
| Returned | A finding from the source session appeared again in its rerun. |
| Introduced | A new finding appeared in a rerun that the source session did not have. |

In the web app, Ask Gauge reads the reruns for you. Gauge wakes the chat when about half the reruns finish, again when all of them finish, and once more for late reruns.

Before you credit an edit, check three things:

1. **Did the rerun read the change?** A rerun that never requested the changed page, Skill, or command tells you nothing about the edit. Treat that result as unclear, not as a failure.
2. **Did the rerun bypass the edit?** An agent can get the old content from another path, a `.md` variant, the other host, a blog post, or `llms.txt`. That is a gap in the tree. Add those URLs with the same change and launch again.
3. **Did the same problem come back in other words?** A finding can return with a different label, or move later in the session.

Criteria and pass rates are noisy at these sample sizes. Report them, but judge the edit by the findings first. For preference, also check what the rerun chose: an objection can resolve while the agent still picks a competitor for another reason.

## Write edits that hold up

A rerun rewards any change that answers the agent, including changes that would mislead real readers. Gauge applies these rules when it edits, and you should too:

* **Keep the purpose of the page.** A quickstart stays a quickstart. Do not add a competitor comparison to a docs root or a sales pitch to a reference page.
* **Make the smallest change that removes the barrier.** Add the one missing example, fix a stale flag or broken link, or move a buried fact to where a reader looks for it.
* **Source every new fact.** Do not estimate prices, limits, or features you have not published.
* **Do not copy the eval into the page.** Do not paste the task's steps, its answer, or a criterion's text as page copy.
* **Do not write for the agent alone.** Skip any "for AI agents" section that a human editor would not publish.

Each edit's note states the benefit to a reader who never sees the eval, the run that hit the problem, and what the edit leaves alone. If no realistic edit exists for a surface, leave it unchanged. Fewer edits are a valid result.

You can edit a page you do not own, such as a third-party comparison article, to test a what-if. You cannot ship that change.

## Lifecycle

1. **Start.** Click **Optimize** on a theme, a finding, or the **Optimizations** page. Starting uses no credits.
2. **Edit.** The tree starts empty. Copy each original into it before you change it, so the diff shows only your edit.
3. **Launch.** Ask Gauge asks before every launch, even in auto mode. Reruns use credits like any run.
4. **Read and repeat.** Edit the tree and launch again until the problem resolves or you decide to stop.
5. **Finish.** Record the result. After you finish, the tree can no longer change, and the optimization moves to **Finished** on the **Optimizations** page.
6. **Ship.** Click **Copy for agent** to copy the changes and evidence as a prompt for your coding agent. Review and publish the change through your usual process.

After you publish, run the eval or preference prompt again against the live product. Try other tasks and models too, to check that the fix helps beyond the source sessions.

## Next steps

> [card] [Improve agent experience](https://docs.withgauge.com/agents/guides/improve-agent-experience.md)
>
> Fix friction in your CLI, Skills, and docs.

> [card] [Improve agent preference](https://docs.withgauge.com/agents/guides/improve-agent-preference.md)
>
> Answer the objections that send agents to other products.


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