Findings CLI

Use provon findings to inspect persisted Findings, record review decisions, create external repair work items, query diagnostic runs, and manage diagnostic Rules. This differs from provon diagnose, which analyzes local evidence without persisting a Finding.

View as Markdown Open the plain-text version of this page.

Prerequisites#

A selected project and authenticated credential.
Read commands require diagnostics:read; review updates, handoffs, work-item writes, and Rule mutations require diagnostics:write.

List Findings#

provon findings list
provon findings list --review-status unreviewed --min-score 0.7 --limit 50

Option	Meaning
`--review-status <status>`	`unreviewed`, `confirmed`, `dismissed`
`--min-score <score>`	Minimum diagnostic score, `0` to `1`
`--last-seen-after <ms>`	Minimum `lastSeenAt` Unix timestamp in milliseconds
`--last-seen-before <ms>`	Exclusive maximum `lastSeenAt` Unix timestamp in milliseconds
`--limit <n>`	Maximum findings, `1` to `500`

Inspect Evidence#

provon findings get <finding-id>

The response contains the Finding, evidence references, diagnostic anchor, per-conversation occurrence data, causal relations, review history, and the current external handoff and primary work item when present.

Record A Review#

Review status and resolution status are updated in separate commands; combining both in one call is rejected (findings.conflicting_update).

provon findings update <finding-id> --review-status confirmed
provon findings update <finding-id> --resolution-status resolved

Dismissing requires an explicit reason:

provon findings update <finding-id> --review-status dismissed --dismissal-reason false_positive

Field	Values
`--review-status`	`unreviewed`, `confirmed`, `dismissed`
`--resolution-status`	`resolved`, `unresolved`
`--dismissal-reason`	`false_positive`, `duplicate`, `accepted_risk`, `not_actionable`, `other`

Dismissing clears resolution state; resolving also confirms the Finding. --dismissal-reason is only valid together with --review-status dismissed.

Hand Off A Repair#

Create a work item through a configured tracker provider:

provon findings handoff <finding-id> \
  --provider github \
  --destination owner=provon \
  --destination repo=provon

Providers: github, gitlab, linear, jira. Destination fields depend on the provider and are supplied as repeated --destination key=value pairs.

Manage Work Items And Handoffs#

# List linked work items
provon findings work-items list <finding-id>

# Inspect or sync a work item with its external tracker
provon findings work-items get <finding-id> <work-item-id>
provon findings work-items sync <finding-id> <work-item-id>

# Replace a work item with a new external one
provon findings work-items replace <finding-id> <work-item-id> \
  --provider linear \
  --destination team=ENG

Retry or abandon a failed creation attempt (a handoff) by handoff id:

provon findings handoffs retry <finding-id> <handoff-id>
provon findings handoffs abandon <finding-id> <handoff-id>

Query Diagnostic Runs#

discover and analyze enqueue asynchronous analysis and return a revision. Query the submitted run:

# Submit diagnostics for the most recent project conversation
provon findings discover

# Enqueue analysis for a specific conversation
provon findings analyze <conversation-id>
provon findings analyze <conversation-id> --last-activity-at 1755216000000 \
  --trace-id <trace-id> --trace-id <trace-id>

# Fetch the submitted run by revision
provon findings run <conversation-id> --revision <revision>

--last-activity-at defaults to now when omitted; repeat --trace-id to bind additional traces.

Manage Diagnostic Rules#

provon findings rules list
provon findings rules get <rule-id>
provon findings rules enable <rule-id>
provon findings rules disable <rule-id>

Replace the full rule configuration object:

provon findings rules configure <rule-id> \
  '{"minSignalScore":0.5,"minDiagnosticConfidence":0.25,"keywords":[],"reviewerDiscoveryPolicy":"candidates_only","reviewModel":null}'

Run a rule over historical conversations:

provon findings rules backfill <rule-id> \
  --start 1755216000000 \
  --end 1755302400000 \
  --max-conversations 1000

--start and --end are required milliseconds timestamps. Automatic diagnosis runs while at least one Rule is enabled; disabling every Rule turns automatic scheduling off.

Success Check#

provon findings list --review-status unreviewed

A healthy result returns ok: true with Finding records; after handoff, get <finding-id> shows a non-empty workItem once the tracker creates it.

Troubleshooting#

Symptom	Likely cause	Fix
`HTTP_403` on update/handoff	Missing `diagnostics:write`	Use a session or key with write access
`findings.conflicting_update`	Both status flags in one command	Split into two `update` calls
`findings.dismissal_reason_required`	Dismissing without a reason	Add `--dismissal-reason` from the allowed set
Handoff stays `failed`	Tracker connection missing or destination wrong	Inspect handoff error, fix the connection, then `handoffs retry`
`run` revision rejected	Stale revision from an older analysis	Re-run `analyze` and use the new revision
No new Findings after activity	All Rules disabled, or conversation below thresholds	`rules list`; enable a Rule or lower score/confidence in `configure`
Backfill returns immediately	Time window outside captured telemetry	Widen `--start`/`--end`; verify traces exist in that window