Investigations
How an investigation runs
A bounded loop, not a chat. Evidence is collected by deterministic tools, hypotheses are written down, and the diagnosis cites the facts it rests on.
Stages
| Stage | Who | Output |
|---|---|---|
| Observe | Environment Analyst (deterministic) | port → process → project → runtime, containers, Git, HTTP |
| Investigate | Evidence Investigator | Evidence items with ids, hypotheses with confidence |
| Diagnose | Diagnostician (model) | Root cause, confidence, evidence refs, alternatives rejected |
| Plan | Remediation Planner (model) | Typed actions, risk, expected effect, checks |
| Approve | Policy engine + you | Allowed, needs approval, or refused |
| Act | Local agent | Action result per step |
| Verify | Deterministic checks | Port, process, container, HTTP status, TCP connect |
Evidence has provenance
Every fact the diagnosis uses is an evidence item with an id, a type, a source and a timestamp. The model cannot invent one: citations to ids that were never collected are dropped. When you see an evidence id in a root cause, you can open it in the dashboard and read what was observed.
evidence
{
"id": "ev_1042",
"type": "process_logs",
"source": "local-agent",
"observedAt": "2026-09-23T09:41:07Z",
"summary": "api: 4× ECONNREFUSED 127.0.0.1:5433 in the last 60s",
"sensitivity": "internal",
"confidence": 1
}Hypotheses are explicit
H1API points to the wrong database port · supported (3 for, 0 against)H2PostgreSQL is not running · rejected by ev_1039H4credentials invalid · rejected by ev_1040
The investigator stops collecting when one hypothesis is supported with high confidence, or when the budget runs out. Budgets cap tool calls (20), model calls (12), wall-clock time (5 minutes) and evidence volume, and a repeated identical tool call is refused.
What a diagnosis must contain
Observed symptom, relevant evidence, inferred cause, confidence, and the affected resources. "The database is broken" is not a diagnosis. "DATABASE_URL targets :5433 while PostgreSQL is exposed on :5432 (ev_1041, ev_1042)" is.