The five fields

Field	What it is for
category	Routing. It answers 'who should look at this' before anyone reads a word of the analysis.
root_cause	Two or three specific sentences naming the file, function and value at fault. Specificity is the requirement — a root cause you cannot act on has not been found.
evidence	Two to five verbatim quotations that make the case checkable without trusting the prose.
confidence	How much of the above is quotation and how much is inference. See evidence and confidence.
suggested_fix	What to change, imperative, one or two sentences — plus a minimal patch where one exists.

Because it is a validated schema rather than free text, a malformed result is a caught error rather than a plausible-looking paragraph with a missing field.

Classification is by cause, not by failing step

This is the distinction that makes the category worth having. A run that failed at Run tests might be a genuine test failure, or a dependency that installed at a version the tests were never written against, or a runner that ran out of disk. All three fail at the same step and all three need a different person.

test_failure — Test failure: Application or test code asserts something that is no longer true.
dependency — Dependency: A package version, resolution or lockfile made the build unbuildable.
config — Configuration: The workflow, tooling config or environment is wrong, not the code.
infra — Infrastructure: The runner, network or an external service failed, not your change.
lint_type — Lint / type: A static check rejected the code before anything ran.
flaky — Flaky: Non-deterministic behaviour: timing, ordering or shared state.
inconclusive — No cause found: Nothing in this run supports a root cause.
unknown — Unclassified: The evidence did not support any single category.

Reading the harder categories

infra is the category that says “this is not your change”. Runner exhaustion, a registry timeout, a service container that never became healthy. Re-running is a legitimate response, which is not true of any other category.
flaky is a claim about non-determinism: timing, ordering or shared state. It is the hardest to prove from a single run, so it usually comes with a modest confidence score and should.
inconclusive means no cause was found. It is a first-class outcome, not a failure to try harder. When the deterministic layer can already see that the failing step's log contains no error, the model is never invoked at all — there is nothing to reason about, and asking anyway produces fluent hedging rather than silence. Such a result carries no suggested fix, on purpose: a fix for a cause nobody identified is the most expensive kind of wrong answer.

The category can be right while the root cause is thin

Categorisation needs much less evidence than root-cause identification. A confident dependency label with a vague root cause is a normal and useful outcome: it has told you where to look even though it could not finish the job.

The suggested patch

Where a minimal patch exists, it is included as a unified diff. It is illustrative: TraceCI has no write access and does not apply anything. It is deliberately minimal — the smallest change that addresses the stated cause — rather than the change you would probably make, because a large suggested rewrite is impossible to review against the evidence.

Read it after the evidence, never before. A patch read first is a suggestion you have to trust; read after, it is one you can check.

Acting on a diagnosis

Read the evidence. Does it say what the root cause says?
Check the category against the failing step. A mismatch is not wrong, but it is the point at which to read more carefully.
Check the confidence. Below 5, find the inferred link and verify it before touching code.
If anything looks off, open the full record and read the log window the agent was given. Input problems are far more common than reasoning problems.

Reading an investigation

The same procedure applied to a real result.

Limitations

Cases where the root cause is systematically unreliable.

The category is shown on every entry in the investigations list, so a pattern across several runs is visible without opening any of them.