# Repair An Agent From Trace Evidence

The repair loop turns a recurring production failure into a reviewable Finding and a scoped work
item for a human or coding agent.

## Before You Start

You need:

- a project with diagnosis-ready trace evidence;
- at least one enabled diagnostic Rule;
- a GitHub, GitLab, Linear, or Jira connector for external handoff.

Complete the [Quickstart](./quickstart.md) first if no traces are visible.

## 1. Reproduce A Representative Failure

Run a real agent task that exhibits the behavior you want to correct. Prefer one complete user goal
over an artificial isolated model call.

Open **Traces** and verify that the trajectory includes the relevant prompt, model, tool, result,
and final-answer evidence.

## 2. Run Diagnostics

Open **Findings** and enable **Auto-diagnose** for future conversations. To process existing
evidence, run an enabled Rule against a selected time window.

A completed Rule Run does not always produce a Finding. Healthy conversations and candidates below
the configured signal or confidence thresholds are intentionally excluded.

## 3. Review The Finding

Confirm that the Finding contains:

- the failure mechanism rather than only a symptom;
- trace or span evidence that supports the claim;
- an appropriate severity and confidence;
- a repair direction narrow enough to implement and verify.

Confirm actionable Findings and dismiss unsupported ones. See [Findings](../findings/index.md) for
the complete review lifecycle.

## 4. Hand Off The Repair

Configure an issue-system connector, then create a work item from the Finding. Provon includes the
goal, cause assessment, evidence, remediation direction, and correlation metadata.

Repository access remains with the user-controlled development workflow. Provon does not check out
the repository or apply code changes.

See [Repair handoff and connectors](../findings/connectors.md).

## 5. Verify The Outcome

After the change is deployed, inspect new traces for the same behavior. A later occurrence can
reopen a resolved Finding as a regression; absence of new evidence should not be treated as proof
that the repair worked.

For local or CI-oriented diagnosis without persisting Findings, use
[CLI diagnosis](../cli/diagnose.md).