# Findings Quickstart

By the end of this guide you will have a real agent trace in Provon, a published Finding, and a
repair issue in GitHub.

## Prerequisites

- A Provon project and API key. See [Install Provon](../get-started/install.md) or the hosted
  Workbench.
- A GitHub OAuth app or personal token for repair handoff.

## 1. Capture A Trace

Choose one path:

### Path A: Provon Gateway

```bash
export PROVON_API_KEY="..."
export PROVON_GATEWAY_URL="https://gateway.provon.dev/v1"

curl "$PROVON_GATEWAY_URL/chat/completions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-otel-gen-ai-conversation-id: quickstart-conversation-1" \
  -H "x-otel-gen-ai-agent-id: quickstart-agent" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Find the failed deployment and fix it."}
    ]
  }'
```

### Path B: OpenTelemetry

```bash
export PROVON_API_KEY="..."
export PROVON_OTEL_URL="https://otel.provon.dev/v1"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$PROVON_OTEL_URL/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
```

Run your instrumented agent once. See [OpenTelemetry setup](../tracing/opentelemetry.md) for SDK
examples.

For the first Finding, it helps if the run includes a tool failure, skipped verification, or
unsupported claim. Healthy conversations often produce no Findings.

## 2. Verify The Trace

Open **Traces** in the Workbench and select the new trace. Confirm that:

- `gen_ai.conversation.id` is stable;
- the root span states the user goal;
- model, tool, and final-answer spans are in causal order;
- a failure or terminal state is visible if you expected one.

See [Diagnosis-ready tracing](../tracing/best-practices.md) if any of these are missing.

## 3. Enable Diagnosis

Open **Findings**:

1. Open **Diagnostic rules** and confirm at least one Rule is enabled.
2. Turn on **Auto-diagnose**.
3. If you already have historical traces, run an enabled Rule against the last 24 hours.

Automatic Runs are queued after a conversation has been inactive for **10 minutes**. The UI updates
when a Finding is published.

## 4. Review The Finding

Expand the new Finding and check:

- **Severity** matches the impact.
- **Diagnostic confidence** is high enough to act on.
- **Cause assessment** points to a failure mechanism, not just a symptom.
- **Evidence** links to the trace/span that supports the claim.
- **Remediation hint** gives a narrow repair direction.

If the Finding is not actionable, dismiss it. If it is actionable, confirm it.

## 5. Hand Off To GitHub

1. Open **Connectors** and expand **GitHub**.
2. Connect with OAuth or paste a token.
3. Set **Default owner** and **Default repo**, then enable the connector.
4. Return to **Findings**, expand the Finding, and select **Confirm & create in GitHub**.

Provon creates a GitHub Issue with:

- a focused repair goal;
- the Finding summary and cause assessment;
- trace and span evidence links;
- a remediation hint;
- the `provon-repair` label and hidden correlation metadata.

The Finding becomes **Confirmed** and tracks the external work item.

## 6. Verify The Outcome

After the fix is deployed:

1. Run the same agent task again.
2. If the failure is gone, no new occurrence is published.
3. If a new occurrence appears, the resolved Finding becomes **Regressed**.

For GitHub, a merged pull request linked to the issue is recorded automatically. For other
providers, mark the Finding verified after you confirm the fix.