--- 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, and who can settle it. Read-only. Use when an issue's cause isn't known yet." metadata: min-cli-version: "0.73.0" next: "platform-resolve" --- # 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. Work through the steps in order without stopping, except where step 5 says to. ## 1. Find which agent it concerns When the issue doesn't settle it, look across the organization's agents, not inside one: ```sh introspection runtimes list introspection events list --event-name introspection.observation # also introspection.annotation, .feedback, .judgement, .pattern introspection metrics query # aggregates, with a runtime_group_id dimension ``` ## 2. Decide what kind of cause it is Decide 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. ## 3. Launch an agent for a bounded investigation Do this when locating the cause would take long or cover several agents. Give it the findings so far, the sources, the outcome wanted and the constraints, and follow up with context: ```sh introspection tasks create --prompt introspection tasks prompt --prompt ``` 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. ## 4. Record what you found on the issue Record 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. ## 5. Ask a person when it's blocked When it's blocked on a decision or context only they have, ask a question on the issue, in the thread too, then set the issue to waiting and end the turn. Otherwise go on. ## 6. Hand over to platform-resolve Hand over 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`.