# Findings Troubleshooting

## No Findings Appear

### 1. Auto-diagnose is off

New projects have automatic scheduling disabled. Open **Findings** and enable **Auto-diagnose**.

### 2. Rules are disabled

Open **Diagnostic rules** and confirm at least one Rule is enabled. The built-in Rules are all
disabled by default until you enable them.

### 3. The trace is not diagnosable

A trace can be valid OpenTelemetry and still too weak for diagnosis. Provon needs:

- a stable `gen_ai.conversation.id`;
- the user goal and constraints;
- ordered model, tool, retrieval, and final-answer events;
- tool inputs, results, failures, and retries;
- a terminal answer or explicit non-completion.

Open the trace in **Traces** and compare it with the checklist in
[Diagnosis-ready tracing](../tracing/best-practices.md).

### 4. The Rule did not run yet

Automatic Runs are queued after **10 minutes of inactivity** on the conversation. For existing
traces, run an enabled Rule against the last 24 hours.

### 5. Keywords filtered the conversation

If a Rule has `keywords`, it only evaluates conversations that contain one of those keywords. Remove
or broaden keywords to test.

### 6. Thresholds filtered the candidate

Increase logging by checking the Rule Run state, or temporarily lower `minSignalScore` and
`minDiagnosticConfidence` to see if a candidate was close. If it appears, tune back up and decide
whether to adjust the override.

### 7. The conversation is healthy

Healthy conversations do not produce Findings. That is the expected result.

## Too Many False Positives

### Raise the confidence bar

Increase `minDiagnosticConfidence`. This is the fastest way to suppress low-confidence candidates.

### Disable noisy categories

Use `signalOverrides` to disable categories that are not actionable in your domain:

```json
{
  "configuration": {
    "signalOverrides": {
      "implicit_user_dissatisfaction": { "enabled": false },
      "context_growth": { "enabled": false }
    }
  }
}
```

### Lower severity, not publication

If a category is useful but rarely urgent, override its severity to `low` or `info` instead of
disabling it entirely.

### Use deterministic-only for screening

If a category requires model adjudication and is too speculative, set the Rule to
`deterministic-only`. You will lose recall on judgment-heavy categories but gain predictability.

## Work Item Errors

### `WORK_ITEM_PROVIDER_UNAVAILABLE`

The connector is missing, disabled, or has no default destination. Open **Connectors**, confirm the
provider is enabled, and set the default owner/repo or team.

### `WORK_ITEM_ALREADY_EXISTS`

A Finding can have only one primary work item. Use **Replace** to move it to another provider, or
**Abandon** the existing handoff first.

### `WORK_ITEM_NOT_RETRYABLE`

Retry only works when the work item is in `provisioning` state, has no `externalId`, and has
`syncState: error`. If creation already succeeded elsewhere, use **Sync** instead.

### `ACTIVE_WORK_ITEM`

You cannot dismiss or manually resolve a Finding while its work item is `provisioning`, `planned`,
or `in_progress`. Wait for the external issue to reach a done state, sync, and then verify.

### Sync returns `failed`

Check the work item error message. Common causes:

- the OAuth token expired or was revoked;
- the external issue was deleted;
- the connector default destination changed.

Reconnect the connector or replace the work item.

## Regression

A resolved Finding becomes `regressed` only when a **new occurrence** is observed after `resolvedAt`.
Historical backfills cannot regress a Finding. If you see unexpected regression, verify that the
new trace was captured after the fix was deployed and that the conversation ID is the same.