Investigate a failure

Compare production evidence, test possible causes, and produce a root-cause report a person can review.

Investigation is for failures that cannot be explained by reading one span. It starts from anchor traces, finds similar runs, compares them with recent baseline behavior, and turns its conclusion into an inspectable report on an incident.

Use it when you need to answer why did this happen, how broadly does it apply, and what evidence would prove an improvement?

An investigation is not a longer trace summary. It should test possible explanations against comparison evidence and state honestly when the available data cannot distinguish them.

Choose a strong starting point

Start from	How to start	Include
Incident	Open it from Incidents and select Investigate further	Symptom, severity, linked runs, expected behavior
Trace	Select Ask neat AI on the trace and ask it to investigate this run, or paste the trace link into investigate	Exact output or span and why it is wrong
Failed Eval	Start from the evaluated trace; there is no investigate control on an Eval result	Question, verdict, rubric, reviewer reasoning
Detection or trend	Start from a representative matched trace, or from the incident Neatlogs raised for it	Detector, time window, representative matches
Search result	In investigate, ask for an investigation of one confirmed trace	Search scope and confirmed examples

The best anchor is the smallest set of evidence that clearly demonstrates the problem. More traces are not automatically better; irrelevant traces dilute the question. An investigation works within a small budget of analysis steps, so a tight anchor and a clear question matter.

An incident may already carry an investigation when you open it. Check its Investigations tab before starting another.

Write the investigation brief

A useful brief contains four parts:

Investigation brief

Observed: refund answers cite policy v2 after its retirement date.
Expected: choose the policy version effective when the request was made.
Impact: customers may receive an invalid refund option.
Scope: refund-assistant / production / last 7 days.

When you start from a chat, send the brief with your request. Do not include an untested implementation claim such as “the vector database is stale” as if it were fact. Put it under a hypothesis if it is worth checking.

Run the investigation

Start the run. On an incident, review the linked traces on the Evidence tab, then select Investigate further. The control is unavailable while another investigation is running or until all of the incident's evidence has loaded. From a chat, the agent replies “Investigation started.” and opens the report as it develops.

Watch how the evidence set develops. In a chat, the report panel shows the investigation's phases (Phase 1: Data Collection, Phase 2: Analysis, Phase 3: Synthesis) and, under Linked Traces, the anchor traces and how many similar traces it found. On an incident, the run appears on the Investigations tab as Running until it finishes.

Supply context that telemetry cannot contain. Investigations do not stop to ask questions, so put authoritative policy or business context in your request. When the failure names a function, error, or file, the investigation also searches apps you connected under Settings → Account → Tools & MCP, such as a code repository, using your own account's access. Connect only the sources the question needs.

Read the completed report. Review Root cause, Evidence & reasoning, and Recommended action, including its Steps, Verification, Risk assessment, and Rollback plan. Open the cited traces instead of relying on the summary alone.

Investigate again when the evidence changes. Select Give feedback on the incident to open the report in a chat, where you can correct a section or ask for the investigation to run again with new context. You can also select Investigate further after new evidence arrives. Each run is listed on the Investigations tab; leave a comment explaining why the conclusion changed.

Read the report critically

Root cause

The root cause should explain the mechanism that produced the failure. “The answer was incorrect” restates the symptom. “The retrieval filter selected policy v2 because the request date was not passed into the query” is causal and testable.

Evidence and reasoning

Every material claim should point to a trace, span, Eval, detection, or connected source. Check whether the cited evidence supports the claim and whether counterexamples were considered.

Recommended action

The action should address the root cause without prescribing unrelated cleanup. It may identify prompt, retrieval, tool, orchestration, or instrumentation work, but a person still decides what should change.

Verification plan

The report's plan appears under Verification in the recommended action. A good plan contains:

the original failing cases;
at least one nearby case that must remain unchanged;
the Eval questions or deterministic checks to run;
the production signal to monitor after deployment;
a condition for reopening the incident.

If the plan is thin, add the missing cases before handing off the work.

Handle uncertainty

Warning

Confidence is not a substitute for evidence. When several explanations fit, keep them separate and request a discriminating test rather than selecting the most plausible story.

Report problem	Best next move
Only one ambiguous trace supports the cause	Add successful and failed comparison runs
A business rule is assumed	Attach the authoritative rule through Give feedback or ask its owner
The needed field was never captured	Improve instrumentation and reproduce the case
Connected context is unavailable	Connect the source under Settings → Account → Tools & MCP, or continue with the limitation stated
Causes conflict across runs	Segment by workflow, version, model, customer, or time

Recognize the possible outcomes

Outcome	How it appears	What to do
Supported cause	The run is Completed, and the report has a root cause and recommended action	Review the report and prepare a focused handoff
No clear cause	“An investigation ran and found no clear cause.” (in a chat: No cause found)	Add context, improve instrumentation, or wait for recurrence
Did not complete	The run is Failed or Cancelled on the Investigations tab, and the incident notes that the investigation did not complete	Resolve the blocker, then select Investigate further
Already tracked	The run is Duplicate; a chat shows Already tracked with View issue, and Activity records Linked to an existing incident	Continue on the existing incident instead of opening parallel work

No clear cause is a valid result. It is different from a failed investigation and safer than selecting the most plausible story.

Know when the report is ready for review

The completed report should let another person:

restate the observed failure and expected behavior;
open the evidence for every material claim;
understand which comparisons were used;
distinguish facts, inference, and missing evidence;
see why the recommended action addresses the cause;
run a verification plan that could disprove the fix.

If the report cannot meet those conditions, add evidence or narrow the investigation before dispatching work.

Frequently asked questions

What can an investigation access?

Traces in the active project: the anchor traces, similar traces, recent metrics for comparison, user feedback signals, Eval results, and earlier fixes on the project. It can also search apps the person who started it connected under Settings → Account → Tools & MCP. Custom MCP servers are not used by investigations.

Can an investigation modify an external system?

An investigation gathers evidence and writes a report. It does not send work anywhere: handing a fix to a coding agent or creating a ticket is a separate action you take after review. Connected apps run with your own account's permissions, so connect accounts with the access you are comfortable delegating.