How optimizations work

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 for friction, or Improve agent preference 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.
• 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

A finding is one problem in one session. An issue groups the same finding across many sessions. Friction issues come from Agent Experience. Objection issues come from Agent Preference. 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: 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