# Using Solvix Reports

This guide explains how to read a Solvix project report and turn it into a practical next step.

Solvix is most useful when you treat it as a decision aid. It helps you choose where to inspect, what to measure, and what not to touch yet.

## Start With The Maintainer Brief

Project mode begins with a maintainer brief.

Read it before the deeper tables.

It answers:

- What kind of project is this?
- Which lens is most relevant?
- What is the current judgment?
- Is there a primary target?
- How confident is Solvix?
- Is this a new or repeated finding?
- What should be checked next?

If the maintainer brief already says `no_send`, do not force an issue or patch from the report. Use the no-send reason to understand why Solvix held back.

## Understand The Judgment

Solvix uses three judgment states.

### Sendable

The target is specific and bounded enough to inspect seriously.

Use this for:

- source review
- benchmark design
- focused tests
- maintainer discussion

Do not treat `sendable` as automatic proof. It means the finding is ready for careful verification.

### Needs Benchmark

The target may matter, but the claim needs measurement.

Use this for:

- microbenchmarks
- input-size comparisons
- before/after prototypes
- source review to confirm whether the path is hot

This is often the right state for mature projects. Mature maintainers usually need evidence before they act.

### No Send

The signal should not become outreach or a patch request.

Common reasons:

- the code is a tiny helper
- the path is tooling, docs, examples, tests, or support code
- the candidate is too broad
- a prior benchmark showed the path is healthy
- Solvix cannot identify a clear function target
- the relevance is too low for maintainer attention

No-send is useful. It protects people from noisy reports.

## Use The Trace ID

Every trace finding has a stable ID:

```text
svx-52422549735e
```

Use this ID when comparing runs or discussing a finding.

A trace finding includes:

- file
- function
- status
- confidence
- target key
- trace steps
- source references

The trace steps show how Solvix got from repository scan to final judgment.

## Use History For Continuous Review

Run with history enabled:

```bash
solvix analyze . --project --history
```

The first run creates a baseline. The next run compares against it.

History states:

- `new`: appeared in this run
- `repeated`: still present with the same status
- `changed`: present, but status changed
- `resolved`: was present before, absent now

Recommended review order:

1. changed
2. new
3. repeated
4. resolved

Changed findings deserve attention first because the codebase state moved.

New findings may indicate new complexity, new runtime work, or a new parser/relevance discovery.

Repeated findings are watch signals. They are not automatically bugs.

Resolved findings should be confirmed, especially after refactors.

## When To Benchmark

Benchmark when Solvix says `needs_benchmark`, or when a `sendable` finding still depends on performance or scaling behavior.

A useful benchmark should:

- use realistic input shapes
- compare at least three sizes
- record the runtime environment
- explain what was measured
- avoid changing runtime behavior in the benchmark-only step

Good benchmark wording:

> This local benchmark checks whether deeply nested input increases work in `formDataToJSON()`. Absolute timings will vary; the relative scaling across input shapes is the signal.

## What Not To Do

Do not open an issue from a raw hotspot alone.

Do not send findings that:

- have no exact file and function
- lack a verification step
- are based only on broad complexity numbers
- are in examples or tooling unless the project treats that path as production
- ignore no-send reasoning

Solvix is valuable when it narrows claims, not when it produces more noise.

## A Practical Weekly Workflow

Use this on your own repository:

```bash
solvix doctor
solvix analyze . --project --history
```

Then review:

1. Maintainer Brief
2. Run History
3. Primary Action Packet
4. No-Send Decisions
5. Trace Ledger
6. Top Prioritized Hotspots

Save JSON when you want an artifact:

```bash
solvix analyze . --project --history --json --output solvix-report.json
```

Store reports from important releases or refactors. Over time, Solvix should help you see whether the same pressure areas are improving, repeating, or moving.

## How To Explain A Finding

A professional Solvix-backed finding should include:

- one bounded claim
- exact file and function
- why it matters for this project
- confidence level
- verification step
- safe first patch shape
- what not to touch
- trace ID

If any of those are missing, keep the finding as internal review until the evidence is stronger.