---
name: platform-investigate
description: "Find where the cause of an issue the Operator is tracking lies across the organization: which agent it concerns, what kind of cause it is (a setup, channel, credential or infrastructure failure, or one agent's behaviour) and who to ask, launching an agent for bounded investigation when it spans several agents. Read-only; reading one agent's conversations, traces and metrics is improve-collect's, which platform-resolve launches. Follows platform-triage; platform-resolve follows."
metadata:
  min-cli-version: "0.73.0"
---

# Platform: investigate

Establish where the problem lies before anyone proposes a fix: which agent, what kind of cause, and who can settle it. This step looks across the organization, records what it finds on the issue, and changes nothing. Reading one agent's conversations, traces and metrics to find what went wrong in its behaviour is improve-collect's, launched through platform-resolve.

## Before you start

- **The issue says what to find out,** and which agent it concerns, from platform-triage. Read it and its conversation first.
- **Read only what you need:** every `introspection` command takes `--query` (JMESPath). How each evidence surface reads and misleads is in improve-collect's references (`references/evidence-surfaces.md` and `references/metrics-query.md` in the improve-collect skill); follow them rather than guessing a field or a filter.

## Steps

1. **Find which agent it concerns,** when the issue doesn't settle it. Look across the organization's agents, not inside one: `introspection runtimes list`, the typed platform events by name (`introspection events list --event-name introspection.observation`, also `introspection.annotation`, `introspection.feedback`, `introspection.judgement`, `introspection.pattern`) and aggregates grouped by agent (`introspection metrics query`, with a `runtime_group_id` dimension). Then go on with step 2.
2. **Decide what kind of cause it is,** from what is true across the organization: how the agent is reached, whether it runs, and what it depends on.

   A setup, channel, credential or infrastructure failure is a blocker for the person who holds it, not a regression in the agent. A cause in one agent's behaviour (what it answered, which tools it called, how often it fails) is found from that agent's own evidence: don't read its conversations, traces or metrics here. Record the agent, the symptom and the hypothesis for improve-collect, which platform-resolve launches. Then go on with step 3.

3. **Launch an agent for a bounded investigation** when locating the cause would take long or cover several agents: `introspection tasks create --prompt <assignment>` with the findings so far, the sources, the outcome wanted and the constraints. Follow up with `introspection tasks prompt <task-id> --prompt <context>`. A prompt answered with 409 wasn't accepted: read the task and its result before sending more, and never start a replacement for work whose delivery is uncertain. Then go on with step 4.
4. **Record what you found on the issue:** the agent, the kind of cause, and the event ids, spans, files and links behind it ([the issue record](references/issues.md)). When the evidence covers only part of the traffic, say so. Never invent an id. Then go on with step 5.
5. **Ask a person when it's blocked** on a decision or context only they have: a question on the issue, asked in the thread too, then set the issue to waiting and end the turn. Otherwise go on with step 6.
6. **Hand over to platform-resolve:** with the cause and its evidence; or, for a cause in one agent's behaviour, with the agent, the symptom and the hypothesis, so it launches improve, whose improve-collect reads that agent's evidence. Close the issue with the reason instead when there's nothing to fix.

## Guardrails

- **Read-only:** no pins, experiments, bindings or pushes here.
- **Never present a guess as the cause.** A hypothesis about one agent's behaviour goes to improve-collect as a hypothesis, not as a finding.
- **Keep raw transcript text, secrets and personal data** out of the issue and the replies.

## Done when

- The issue names the agent and the kind of cause with its evidence, a hypothesis handed on for improve-collect, or the blocker and who has been asked.

Then go on with platform-resolve.