How investigations work

An investigation isn’t a single prompt to a model. It’s a structured process that gathers evidence, forms a hypothesis, then tests that hypothesis against your code and telemetry — refining its conclusion as new evidence arrives. This page explains how that process works, so you know what to expect from the results and why connecting more sources makes investigations better.

​

The shape of an investigation

Every investigation moves through three phases. The first two phases run the same way for every incident — they’re the foundational legwork. The third phase is where each investigation becomes specific to your incident, shaped entirely by what the evidence reveals.

​

Investigations run throughout the incident

An investigation doesn’t stop after its first report. It keeps running for as long as the incident is live, re-assessing as the situation changes. New activity in the channel, fresh alerts, a third-party provider changing state, or a responder steering it — any of these prompt the investigation to gather new evidence and reconsider its hypothesis. This means the investigation stays current with the incident rather than going stale the moment it posts. If the cause shifts, or new information rules out the original theory, the investigation follows along.

​

From evidence to findings

The investigation reasons in terms of findings — concrete hypotheses about what happened, each backed by evidence.

• A finding is a claim, like “a recent deploy introduced a query that locks the orders table under load.”
• Evidence is what supports or contradicts it: a specific Slack message, a pull request diff, a metric spike, a line of code.
• Each finding carries a confidence level, so you can see how sure the investigation is.

Findings evolve as the investigation progresses. A hypothesis that looks promising early on can be discounted when later evidence contradicts it — and the investigation keeps that audit trail rather than quietly dropping it. The final report surfaces only the findings still standing, each linked back to the evidence behind it.

​

Building conviction

An investigation doesn’t just look for evidence that fits its theory — it spends as much effort trying to break it. Roughly half of an investigation’s work goes not into forming a hypothesis but into challenging and proving it: looking for the evidence that would disconfirm the leading theory, ruling out the alternatives, and, when it confirms a trigger like a deploy, checking what else that trigger might have affected. A theory that has only ever been supported, and never tested, isn’t one it trusts. This is why an investigation won’t claim more certainty than it has earned. Before it presents a hypothesis, it grades its own conviction in it, based on how strongly the evidence backs it — and that grade drives the confidence you see in the channel. Two outcomes override that ladder: a hypothesis is marked contradicted when newer evidence disproves it, and flagged when an alternative is just as likely — two theories with equal support that the evidence can’t yet separate. An investigation only reaches the top of the ladder — and only tells you it’s highly confident — when it has found compelling, verifiable evidence against the data sources it trusts, like your logs, metrics, and traces. When it can’t find that proof, it says so: it lowers its confidence and is explicit about what it couldn’t confirm, rather than dressing a guess up as a conclusion.

​

Reading your code

When an investigation needs to understand the code itself, it does more than search for keywords. It works out which repositories are relevant from the incident’s context, plans the specific questions worth answering — “where is this value set?”, “what changed here recently?” — and then reads the code to answer them. All code analysis runs inside isolated, sandboxed containers. Repositories are cloned into ephemeral workspaces and deleted after use. See Code setup for how access and security work.

​

Querying your telemetry

Investigations query the same logs, metrics, traces, and dashboards your responders reach for. Rather than blindly running queries, the investigation learns the shape of each connected data source — its labels, common query patterns, and the dashboards your team actually uses — so its queries are relevant to your systems. See Telemetry for the providers you can connect.

​

Checking your dependencies

Not every incident is your fault. Alongside everything else, an investigation checks whether the third-party providers you depend on — AWS, GitHub, Stripe, and the like — were having an outage around the time of your incident, and surfaces any that could explain it. This needs no setup. See Third-party dependencies.

​

What you get

The investigation posts a summary into the incident channel and keeps it up to date as it runs, with the same detail available on the incident in the dashboard. It surfaces:

• A summary — the headline conclusion in plain language.
• Findings — the hypotheses that survived, each with its confidence and supporting evidence.
• Evidence — links straight back to the source: the Slack message, the pull request, the dashboard, the log line.

As it learns more, it threads progress onto the summary and posts a heads-up when it discovers something important — and you can ask it questions or steer it at any point by tagging @incident. See Incident channel experience for what this looks like and how to interact with it.

​

Investigate alongside the agent

The investigation runs centrally, but you don’t have to work apart from it. With the incident.io desktop app, you can pull a live investigation into a local coding agent such as Claude Code, Codex, or Cursor and investigate side by side — each of you informing the other. It works as a loop:

• Pull the investigation in — your local agent downloads the full investigation: its findings, the checks it ran, the incident context, and the conversation so far. It can read all of this alongside your actual codebase.
• Get live updates — as the central investigation learns more, your local agent keeps in sync, so you’re always working from its latest thinking.
• Send what you find back — when you spot something the investigation hasn’t — the real cause, a misleading metric, a wrong turn it’s taking — you can steer it. Your local agent feeds that back, with evidence, and the central investigation re-assesses its hypothesis within a few minutes. Your input is attributed in the incident channel, so everyone sees where a change in direction came from.

The two work as a pair: the central agent does the broad, continuous legwork across all your sources, while you and your local agent go deep on the code in front of you — and neither of you loses what the other finds.

​

Tuning how deep investigations go

Investigations run more than one pass of analysis by default, refining the hypothesis each time. More passes mean a more thorough investigation but a slower one. If you’d like to adjust how deep investigations go for your organization, reach out to us.

​

Where to go next