Findings

Use this page for the conceptual model, then see:

• Quickstart — first trace-to-Finding flow.
• Repair loop — turn supported failures into scoped repair work.
• Repair handoff and connectors — GitHub, GitLab, Linear, and Jira work items.
• Findings API — HTTP contract for automation.
• Trace diagnosis with CLI — local, non-persisted diagnosis.
• Get started troubleshooting — no findings, false positives, and work-item errors.

Rule, Run, Finding, Occurrence#

Provon keeps diagnosis in three layers:

The execution path is:

flowchart LR
  spans["OTel spans"] --> facts["Conversation facts"]
  facts --> signals["Diagnostic signals"]
  signals --> adjudication["Adjudication"]
  adjudication --> candidates["Finding candidates"]
  candidates --> occurrences["Finding occurrences"]
  occurrences --> findings["Finding clusters"]

A Rule Run can complete without publishing a Finding. That is the expected result for healthy conversations or candidates below the configured thresholds.

In The Workbench#

The Findings page shows clusters ranked by diagnostic score. Use the filter scope to switch between active, dismissed, resolved, and all.

The Diagnostic rules popover in the Findings page lists the five built-in Rules:

Each Rule can be enabled or disabled, and each exposes:

• Keywords: only evaluate conversations containing at least one configured keyword.
• Publication confidence (minDiagnosticConfidence): the minimum confidence required to publish a candidate as a Finding. Default 0.25.
• Minimum signal score (minSignalScore): the minimum score for a signal to enter diagnosis. Default 0.25.
• Adjudication mode: auto (deterministic signals plus model adjudication) or deterministic-only (no model calls).
• Adjudication model: override the deployment default for signals that need judgment.
• Signal overrides: enable or disable individual category kinds and override their severity.

See Diagnostic rules on this page for the full category reference and tuning guidance.

Automatic And Manual Runs#

Automatic scheduling is disabled when a project is first created. Enable Auto-diagnose on the Findings page to schedule Runs for newly ingested conversations.

Automatic behavior:

1. New trace activity is mapped to a stable conversation identifier.
2. Enabled Rules are queued for that conversation activity snapshot.
3. Each Run becomes available after 10 minutes of inactivity.
4. Newer activity supersedes an older automatic snapshot.
5. Duplicate Runs for the same Rule, conversation, and activity snapshot are not created.

For existing data, open Diagnostic rules and run an enabled Rule against the last 24 hours. The API also supports explicit time-window backfills and on-demand Runs.

Reading A Finding#

The inbox ranks Finding clusters by diagnostic score and then by creation time. Review state and repair state remain visible separately rather than changing the canonical score ordering.

Expand a row to inspect:

• Severity: critical, high, medium, low, or info.
• Diagnostic score: the strength and impact used to rank the diagnosed problem.
• Diagnostic confidence: how strongly the available evidence supports the diagnosis.
• Cause assessment: the most likely supported cause.
• Remediation hint: a focused repair direction, not an automatic code change.
• Latest occurrence evidence: trace, span, or aggregate references with locations and quotes.
• Evidence window: the activity used for the latest occurrence.
• Occurrence count: distinct observations grouped under the same cross-conversation failure mechanism.

Score and confidence are separate. A high-impact problem can still have low confidence, and a well-supported issue can be low severity.

Review And Repair Lifecycle#

Review state and repair state are deliberately independent:

flowchart LR
  unreviewed["reviewStatus: unreviewed"] --> confirmed["reviewStatus: confirmed"]
  unreviewed --> dismissed["reviewStatus: dismissed"]
  confirmed --> issue["Finding work item"]
  issue --> verify["awaiting verification"]
  verify --> resolved["resolved"]
  resolved --> regressed["new later occurrence"]

• Confirm accepts the Finding as actionable.
• Dismiss removes it from the default inbox without deleting its evidence.
• Create work item creates a provider issue and confirms the Finding in one action.
• Resolve manually closes a Finding even when no external tracker is connected.
• Retry, Replace, and Abandon recover failed or disconnected handoffs without deleting their history.
• Resolved means repair was verified automatically or explicitly by a user.
• Regressed means a new occurrence was observed after resolvedAt.

Important constraints:

• A Finding with an active work item (provisioning, planned, or in_progress) cannot be dismissed or manually resolved.
• Creating a work item automatically confirms the Finding.
• Replaying the same activity revision is idempotent and does not increase the occurrence count.
• Historical backfills cannot regress a Finding resolved after that historical evidence.

Provon never checks out the repository or applies a patch. A user, Claude Code, Codex, or another controlled coding-agent workflow consumes the external work item and produces the repair.

Repair Handoff#

Repair handoff supports GitHub, GitLab, Linear, and Jira. Configure an enabled project connector with a default destination before creating a work item.

Each issue contains:

Goal
What is wrong
Cause assessment
Evidence
Verification
Provon correlation metadata

All supported providers receive a stable marker derived from the Finding work-item ID so retries can recover a remotely created issue after a local commit failure. GitHub can automatically verify a merged pull request with successful checks. GitLab, Linear, and Jira completion enters awaiting_verification until a user verifies the repair.

See Repair handoff and connectors for OAuth, token, and repository configuration.

Data Requirements#

Diagnosis works best when telemetry preserves:

• a stable gen_ai.conversation.id;
• the user's goal and constraints;
• ordered assistant, model, and tool events;
• tool inputs, results, failures, and retries;
• a terminal answer or explicit non-completion;
• trace and span identifiers for evidence links.

If conversation identity or raw span evidence is missing, Provon may still show telemetry while skipping diagnosis because no usable trajectory can be reconstructed.

See Diagnosis-ready tracing for the practical review workflow and Trace model and instrumentation for boundary guidance.

CLI Diagnosis#

provon diagnose <source> runs the same built-in Rule definitions over a trace source. Results are returned to the caller only: they are not persisted, do not enter the Findings inbox, and cannot create a repair issue. Persisted Findings are produced separately by server-side Rule Runs over ingested project evidence.

See Trace diagnosis with CLI for deterministic screening and hash-bound Agent adjudication.