/incident-investigation

name: incident-investigation
description: Investigate one UniFi Network device incident (a switch, AP or gateway going offline, disconnecting or misbehaving) over an explicit, bounded time window, with Protect camera context, using only the local read-only evidence tools. Produces a cited report that states its coverage. Use when the user asks what happened to a Network device at a given time.

Network Device Incident Investigation

Investigate one Network device incident over one explicit window. Every claim in the report cites **evidence**: records and per-source **coverage** returned by the two incident evidence tools. Each tool returns a bounded **view** of its evidence document (`schema: "unifi-incident-evidence-view"`) that fits in one tool result: every source's outcome, failure and coverage, plus the record citations that fit (at most `max_records_returned`), with omitted records counted and a cursor to read the rest. The local product servers are the whole transport; nothing here needs the cloud worker or the relay.

Dependencies

Requires: network, protect Optional: worker

The investigation needs `unifi_get_incident_evidence` (Network) and `protect_get_incident_evidence` (Protect). Discovery shows a tool is listed, not that its controller is reachable or authorized; the evidence documents report that per source.

• **Protect not connected.** Stop the canonical investigation and report Protect

unavailable. Offer a Network-only investigation; with the user's consent, run the same workflow without the Protect call and label the report "Network-only: Protect unavailable, no camera context". A Network-only report never reaches complete coverage of the incident.

• **Network not connected.** Stop and report Network unavailable. There is no

device evidence to investigate.

• **Cloud worker.** Not needed. Its location timeline, reached through a

connected relay, collects the same evidence through these two tools and returns one combined document; this workflow calls the tools directly so each product's document and budgets stay separate. When you reach the product servers through the cloud worker, call the same two evidence tools.

Use the product setup skills for connection help; never ask for secrets.

Coverage and Limitations

Every report has a Coverage and Limitations section built from the evidence documents, never from memory or from record counts alone:

• One line per evidence document: `overall`, `coverage_complete` and budgets.
• One line per document on `record_selection`: records returned, collected and

omitted from the view.

• One line per source in each document: outcome, partial reasons, failure,

queried window, filters, pagination, truncation, retention and counts (formats under [Report](#report)).

• Products, cameras and mappings that were not read, and why.

Claims are bounded by coverage:

• **Complete coverage** ("every source read the full window") only when every

document in the investigation has `coverage_complete: true` and `overall` is `complete` or `empty`.

• **All-clear** — the sentence "No events were recorded in the window by any

source." — only when every document has `overall: "empty"` and `coverage_complete: true`, and Protect was read. Otherwise write "No concerning activity found in the retrieved records" with the coverage gap beside it.

• **Retention.** Neither product reports how long it keeps events, so every

source's `coverage.retention_coverage` is `unknown`. Whenever any source is `empty`, including beside the all-clear, write this sentence: "Neither controller reports how long it keeps events (retention `unknown`), so events older than its retention may have been discarded without a trace."

• Counts are retrieved records. `population_total` is a total only when the

source is complete.

• Records omitted from the view (`record_selection.omitted`) are a

presentation limit, not a coverage gap: coverage and counts still describe every collected record. Make no claim about omitted records beyond their counts. Records counted in `too_large` have identifiers too long to cite in a view, or a citation too large to fit beside its sources; only `detail="full"` shows them.

• A record's `truncated` names free text the view cut to a prefix (`summary`,

`event_type`, `original_value`, `source_tool`) with its full length; a source's `truncated` names its labels cut the same way (`source_tool`, `controller_id`, `site`, `location_id`). Quote only the prefix, mark it as cut, and claim nothing about the text that was cut off.

• A failed source (`unavailable`, `auth_failed`, `permission_denied`,

`timeout`, `unsupported`, `parse_failed`, `not_attempted`) is missing evidence, never an empty result.

Safety

The investigation reads; it never changes anything.

• Call only tools the client lists with `readOnlyHint: true`. Reach every tool

directly by its own name; the lazy-mode `*_execute` and `*_batch` dispatchers are not read-only and are not part of this workflow.

• Make no remediation, configuration change, reboot, block, acknowledgement or

other mutation, even when the cause looks obvious. Recommend actions in words for the user to decide.

• Investigate the one confirmed window, once. Continuous monitoring, polling or

subscriptions are outside this workflow.

• Offer only reads the directly listed read-only tools can make: the two

incident evidence tools for exact identifiers, `protect_get_camera` by camera ID and `unifi_get_client_details` by MAC. Never offer to list devices, cameras, access points or doors, and never reach for `*_load_tools`, `*_execute` or `*_batch`.

• When an identifier is missing, ask the user for it: they can find it in the

UniFi app, or by running the product's own list tool in eager mode.

• Never page with `resume_after`, split the window, raise a budget or call

`detail="full"` without the user's yes to that follow-up. Offer it, end you