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

# Fix gaps and keep regressions

> Diagnose each failure in a run, get a ranked fix plan with evidence and code locations, and keep confirmed gaps as replayable regressions.

The fix stage is where failures turn into changes you can make. It:

* **Finds the root cause:** traces each failure to its [gap](https://docs.plurai.ai/concepts.md#param-gap) and the code that causes it, with quoted
  evidence and a confidence level.
* **Proposes a fix:** the smallest change that should close each gap, ranked in a [fix](https://docs.plurai.ai/concepts.md#param-fix) plan.
* **Leaves the changes to you:** nothing in your code changes until you choose which fixes to apply.
* **Keeps it from coming back:** records a fixed gap as a [regression](https://docs.plurai.ai/concepts.md#param-regression), so the next suite
  catches it if it returns.

[1 · Scan](https://docs.plurai.ai/guides/scan-your-agent.md)
→
[2 · Ground (optional)](https://docs.plurai.ai/guides/ground-in-production-traces.md)
→
[3 · Build the suite](https://docs.plurai.ai/guides/build-the-suite.md)
→
[4 · Run](https://docs.plurai.ai/guides/run-the-simulation.md)
→
[5 · Fix](https://docs.plurai.ai/guides/fix-and-keep-regressions.md)

**With `/simulate`:** the flow ends here, with the fix plan: the root cause and a proposed fix for each gap. It applies nothing.**With `/simulation-fixes` on its own:** it diagnoses your latest run, writes the plan, then lets you pick the fixes to apply and check them with `--verify`. Run it after every run with failures.

## Apply the fixes `/simulate` found

`/simulate` ends with the fix plan in your report and in `plurai_sim/artifacts/fixes.md`. Your code is untouched. To apply the fixes:

**1. Review the plan**

Open the **Gaps** stage of your report. Each gap shows its root cause, where it broke and the proposed fix.

**2. Pick the fixes and apply them**

Choose one way:

* **Run `/simulation-fixes`.** It picks up your latest run, asks which fixes you want, and applies each one as a diff you can review.
* **Ask in chat**, for example "Apply the fixes for the refund gaps." Your coding agent applies them from the plan.
* **Apply them yourself** from `fixes.md`: each issue gives the file, the line and the proposed change.

**3. Check that they held**

Run `/simulation-fixes --verify`. It re-runs the scenarios that exposed each fix and marks it **fixed**, **still caught** or **not yet shown**.

## What you get

![Gaps and fixes in the report](https://mintcdn.com/plurai/V3XeGRFO5iyJejs5/images/report/gaps.png?fit=max\&auto=format\&n=V3XeGRFO5iyJejs5\&q=85\&s=bb915a0d2029bf50e189cf45108608b5)

The Gaps stage of the report: every gap ranked by severity, with where it broke and its proposed fix.

In chat:

> Diagnosed 6 failures — 3 look like agent bugs, 2 test-setup, 1 mock-env.
> Also carrying 2 potential issues flagged while building, which may be intended.
> Open the fix plan →

Each issue in `fixes.md` has:

| Field | What it says |
| - | - |
| **Symptom** | What went wrong in the conversation. |
| **Evidence** | Quotes from the transcript, tool calls or verdicts. |
| **Root cause (likely)** | The cause and its home, with a confidence of high, medium or low. |
| **Where** | The file and line, for example `agents/billing/refunds.py:142`. |
| **Proposed fix** | The change. An agent fix quotes the replacement text. |
| **Regression** | Whether a regression was recorded for it. |

A final section lists the **potential agent issues** the scan and suite flagged that may be intended. They are not ranked. `fixes.md` and `agent_findings.md` are staged in git so your team can read them. See [Gaps and fixes](https://docs.plurai.ai/report/gaps-and-fixes.md) for how they appear in the report.

## Diagnose a run

```bash theme={null}
/simulation-fixes
```

Or say it in chat: "Why did those scenarios fail?"

| Argument | What it does |
| - | - |
| `--run <out-dir>` | The run to diagnose. Defaults to the most recent run. |
| `--verify` | After you accept fixes, run the suite again to check them. |

If there is no run yet, run `/simulation-run` first. You can also run `/simulation-fixes` straight after building the suite: it can work from issues the suite build already confirmed, with no new run.

## What happens

**1. The plugin reads the run**

It reads each failing scenario's transcript, tool calls, eval verdicts and errors, along with the issues already recorded in `artifacts/agent_findings.md`.

**2. It finds where each failure comes from**

Each failure gets one home:

* **Agent bug**: a real defect in your agent's own code.
* **Test setup**: the harness, the configuration, a scenario's seed, or an eval that is too strict.
* **Mock environment**: the seeded data or the mocked tools. These are fixed on the Plurai side during diagnosis.

Every claim quotes its evidence. A failure without evidence is marked **needs investigation**, not guessed at.

**3. It writes the fix plan**

The plan ranks the issues and proposes the smallest reversible fix for each. It goes into `plurai_sim/artifacts/fixes.md` and the report.

**4. You decide what to apply**

Applying fixes is a separate step that you start. Nothing runs on its own, and you choose how involved you want to be:

* **Ask the plugin to apply them:** pick the fixes you want, or the whole plan, and each one is applied as a diff you can review.
* **Work through it interactively:** go fix by fix, and ask for a different approach in chat.
* **Apply them yourself:** use `fixes.md` as your guide, with the file, line and proposed change for each issue.

Then [check them](#check-your-fixes) with
`/simulation-fixes --verify`.

The plugin never edits your agent's source on its own. It changes your code only after you accept that specific fix.

## Check your fixes

```bash theme={null}
/simulation-fixes --verify
```

`--verify` runs the scenario set again into a new run folder and checks each accepted fix over several trials on the scenarios that exposed it. Each fix is marked **fixed**, **still caught** or **not yet shown**, and `fixes.md` gets a column with the result. To save time you can verify only the failing scenarios; the plugin then says the rest were not checked.

Nothing is called fixed until it is verified.

## Keep a gap as a regression

When you accept a fix for an agent bug, the plugin records the gap as a regression before it applies the edit. You don't need to do anything. To record one by hand:

```bash theme={null}
/record-regression --issue 2
```

| Argument | What it does |
| - | - |
| `--run <out-dir>` | The run the gap was found in. Defaults to the most recent run. |
| `--issue <n>` | Issue number `n` in `fixes.md`. |
| `--finding <id>` | A confirmed finding in `agent_findings.md`. |
| `--scenario <name>` | The scenario to replay. Defaults to the shortest failing one. |
| `--cut-turn <K>` | The turn to cut the conversation at. Defaults to the turn the gap is on. |
| `--slug <name>` | The regression's name. |

### What a regression is

A regression is a folder under `plurai_sim/regressions/` that replays the conversation that exposed the gap, cut just before the turn where your agent went wrong:

```text theme={null}
plurai_sim/regressions/
  BUNDLE.md
  regression_refund_timing_invented/
    ROLES.md            # the issue: what to probe, the evidence, why it is the agent
    issue_turn.json     # the turn as recorded
    resume_pin.json     # the conversation up to that turn
    transcript.md       # the same, as prose
```

Before it keeps the folder, the plugin replays your agent from the cut 5 times and tells you how reliably it reproduces the gap, for example "caught again in 4 of 5 replays at that turn". If none of the 5 replays reproduces it, the folder is not kept.

The `regressions/` folder is meant to be committed.

### How the suite uses it

A regression joins your scenario set at the next `/simulation-generate-suite`, as one extra scenario in the final batch. After that, every run replays it several times. Until then, `--verify` checks the fix through the original scenario, and `/simulation-run` warns you when a recorded regression is not yet in the set.

Regressions stay after the gap is fixed. To retire one, delete its folder.

### When a regression is not recorded

The plugin does not record a regression when:

* The issue is only a potential issue that no run confirmed.
* The issue's home is not your agent.
* A test-setup or mock-environment issue touches the same scenario. Fix that first, run again, and record from the clean run.
* A folder for that issue already exists.
* The installed SDK is too old. Update it and run `/record-regression` again.

When you accept a fix and the regression is refused, the fix is still applied and the plugin tells you why.

## Next steps

> [card] [Replay from where it broke](https://docs.plurai.ai/guides/replay-production-conversations.md)
>
> Turn real production failures into scenarios for your next cycle.

> [card] [Gaps and fixes](https://docs.plurai.ai/report/gaps-and-fixes.md)
>
> The fix plan in the report.

> [card] [Build the suite](https://docs.plurai.ai/guides/build-the-suite.md)
>
> Rebuild the suite so it carries your regressions.

> [card] [Shape your simulation](https://docs.plurai.ai/guides/iterate.md)
>
> Change scenarios, evals or the mock environment.

> [card] [Concepts](https://docs.plurai.ai/concepts.md)
>
> Gaps, regressions and the rest of the vocabulary.


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