# 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. A runnable end-to-end
example is in [`examples/diagnostics-findings`](https://github.com/provon/provon/tree/main/examples/diagnostics-findings).

## 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](../findings/repair-handoff.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).

## Example: end-to-end shell flow

The [`examples/diagnostics-findings`](https://github.com/provon/provon/tree/main/examples/diagnostics-findings)
example emits an OTLP trace with a stable `conversation.id`, triggers an on-demand diagnostic Rule
run, and polls for produced Findings. You can adapt the same pattern to hand a Finding off to
GitHub once it appears.