Investigations

Version: 1.5 | Last updated: 2026-09-14

An investigation is how Bluebox goes deep on a problem. Where chat gives you a fast answer, an investigation works the problem end to end: it traces the issue through your service topology, forms and tests hypotheses, and assembles evidence from your live telemetry, then hands back a structured, evidence-backed result you can act on. This is the core of the Bluebox SRE agent.

Where to start an investigation

There are two ways in, depending on what you already know:

• From a finding. When Bluebox has already detected a problem, open the Overview page and select Investigate on the finding's row. Bluebox starts with the finding's context already loaded, which is the fastest path.
• From the Investigations page. Open Investigations from the sidebar, select New investigation, and describe the incident in your own words: paste in an error, name a service that's misbehaving, or ask what's wrong. Use this when you have a symptom but no finding yet. (You can start the same way from the Overview page.)

The clearer your description, the sharper the investigation. Copying the title and body of an existing GitHub issue into the prompt is a good starting point.

When someone is already investigating

If a colleague is already investigating the same incident and has shared that investigation with the workspace, Bluebox tells you before starting a second one. Instead of an error you get a choice, showing the running investigation's title and when it started:

• Open existing investigation takes you to it, so you can follow along and read the evidence as it arrives. You get read access — the member who started it stays in control of it.
• Start mine anyway creates your own investigation into the same incident. Use this when you need a separate line of inquiry, or when the running one is about to finish. A second investigation counts against your workspace's usage the same as any other, so choose it deliberately.

Two cases never produce this choice. If the match is your own still-running investigation, Bluebox opens that one for you rather than starting a duplicate. If the match is a colleague's investigation that has not been shared, Bluebox says nothing about it and starts yours as usual.

What Bluebox does

Bluebox works through the problem in visible phases (getting situational context, forming and testing hypotheses, investigating the evidence, and reporting) and streams its progress to the investigation timeline as it goes, with a short summary for each phase it completes. You can watch the evidence it gathers build up in real time, keep the tab open, or come back to it later.

What you get

When an investigation finishes, it produces an evidence-backed root-cause report on the investigation's page:

• Root cause — what actually went wrong, stated plainly.
• Evidence — the specific telemetry behind each step of the diagnosis, not a log pattern-match. Every claim traces back to a signal.
• Affected services and endpoints — where the problem shows up in your topology.
• A recommended fix — concrete guidance you can implement yourself or hand to your coding agent.

The report is shown as one Investigation Report card, divided into sections (Summary, Impact, Root Cause, Recommendation, Evidence, and more) that you can expand or collapse individually. Summary, Impact, Root Cause, and Recommendation start open so the story and the recommended fix are visible at a glance; Evidence, Tracking Issue, and Investigation Metadata start collapsed, and you expand them when you need the detail. Each section has two controls: the star (☆) pins it to the investigation's pinned list at the top of the page, so the parts you care about stay one click away (select the star again to unpin); the copy control puts that section's text on your clipboard to paste elsewhere. Pins belong to the investigation, so anyone you share it with sees the same pinned sections. Read-only members can read and copy every section and see the pins, but only the investigation's owner or the workspace owner can pin and unpin.

Bluebox also files the result as a GitHub issue in your connected repository for actionable findings, so it lives where your team already works. You can comment on it, assign it, or paste it straight into a coding agent to open a pull request. Whether an issue is filed follows the workspace's GitHub issue policy (smart by default; always or never available): smart files actionable findings and skips inconclusive runs and repeat firings of an already-open problem. Workspace owners set this policy under Settings → Investigations; other members see the current value. Your coding agent can pull the investigation's full context on demand while it works the fix.

What to investigate

Reach for an investigation whenever you need a diagnosis backed by evidence rather than a quick answer:

• A spike in errors or latency on a service, especially after a deploy.
• A recurring failure you've seen in the logs but haven't traced to a cause.
• A customer-reported incident where you have a symptom but not the source.
• An open GitHub issue describing unexpected behavior in production.

For quick lookups and exploration ("what are the top findings right now", "is checkout healthy"), use chat or bluebox ask instead, and open an investigation when you need the structured result.

Investigation states

Your investigations are accessible from the sidebar or the dedicated Investigations page. Common states include:

State	Meaning
Open	Ready to be investigated
Investigating	Bluebox is actively working on it
Resolved	Marked as resolved
Completed	Bluebox finished the investigation and produced its final report
Cancelled	You stopped the investigation before it finished, or the underlying task was terminated by the system (for example, a timeout, internal failure, or resource limit). It cannot be resumed, and its conversation accepts no further messages.
Archived	Closed and stored for reference