Update to Ansight

{
  "name": "ansight-investigate-session",
  "description": "Investigate one live or recorded Ansight session through retained evidence. Use to bracket and correlate logs, network, telemetry, screenshots, trees, touches, artifacts, and annotations or create an evidence slice; do not use to prepare the workstation, drive the live UI, or write annotations.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 328
    }
  ],
  "skill_md_contents": "---\nname: ansight-investigate-session\ndescription: Investigate one live or recorded Ansight session through retained evidence. Use to bracket and correlate logs, network, telemetry, screenshots, trees, touches, artifacts, and annotations or create an evidence slice; do not use to prepare the workstation, drive the live UI, or write annotations.\n---\n\n## OpenAI plugin integration\n\nRun Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.\n\nUse these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:\n\n- https://www.ansight.ai/skills/ansight-install.md → [ansight-install](../ansight-install/SKILL.md)\n- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)\n\n\n# Investigate An Ansight Session\n\nBuild a timestamped evidence trail from one exact session before reading source code or proposing a cause. Treat missing evidence as a finding, not permission to fill gaps with assumptions.\n\nUse `--json` throughout. Keep timestamps in UTC and preserve source IDs such as frame IDs, snapshot IDs, request IDs, annotation IDs, channel IDs, and artifact snapshot IDs.\n\n## Prerequisites And Routing\n\nRecorded-session investigation requires the Ansight CLI or another exposed Ansight diagnostic surface and a session available from local history or an imported archive. The target app does not need to remain installed, connected, or currently integrated with the SDK when retained evidence is sufficient.\n\n- For a live investigation, the app's development or QA build must contain an initialized Ansight SDK and be connected to the host. Use the Ansight Operate Live App skill to establish that session.\n- If the SDK integration is missing and new live evidence must be captured, follow `https://www.ansight.ai/skills/ansight-install.md`.\n- If the CLI or resident host cannot access local or imported sessions, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.\n\nDo not require or install the SDK merely to inspect an existing recorded or imported session.\n\n## Select The Session\n\nStart with focused discovery. When the user supplied an exact session ID, query\nthe lightweight session-summary index and confirm that the returned\n`sessionId` is an exact match:\n\n```sh\nansight session list --app-id <app-id> --from <utc> --to <utc> --limit 20 --json\nansight session list --search <session-id> --limit 1 --json\n```\n\nDo not use `ansight session show <session-id> --json` for discovery. Its JSON\nresponse can materialize the session's retained logs, metrics, and visual trees,\nwhich is unnecessarily large for agent context. Use the summary index above,\nthen query only the evidence surface needed for the investigation.\n\nAdd `--connected` only when the task requires a live session. Use app identity, device profile, capture time, tags, retained evidence totals, and connection state to choose. Do not silently choose among multiple plausible sessions.\nThe time filters select sessions whose capture intervals overlap the requested\nrange. Follow `nextCursor` with `--cursor` only when the first filtered page is\ninsufficient, preserving the same filters between pages.\n\nRead existing annotations early because they may already define the relevant moment or region:\n\n```sh\nansight session annotations <session-id> --json\n```\n\n## Bracket The Investigation\n\nDefine the smallest interval that can answer the question. Prefer, in order:\n\n1. an existing annotation's `startUtc` and `endUtc`;\n2. a stable app event, log, request, touch, or screenshot timestamp near the reproduction;\n3. a narrow interval around a telemetry detector result;\n4. the whole session only when no reliable anchor exists.\n\nState the interval before correlating evidence. Expand it deliberately when a cause may precede the visible symptom.\n\n## Reuse Workspace Evidence Boundaries\n\nWhen a linked `ansight/` workspace exists, use its maintained definitions as evidence leads: Trends results can provide established observation spans, telemetry budgets, and regression comparisons, while triggers can explain automatically captured artifacts. Confirm that each definition's App ID, event labels, inputs, and session match the investigation before relying on it. Route any request to create or change these definitions to the Ansight Workspace Automation skill.\n\n## Build The Evidence Stack\n\nUse the surfaces that match the hypothesis rather than dumping every retained item.\n\n### Logs And Network\n\n```sh\nansight session logs <session-id> --start <utc> --end <utc> --minimum-priority warning --json\nansight session logs <session-id> --start <utc> --end <utc> --contains <text> --json\nansight session network <session-id> --start <utc> --end <utc> --failed --json\nansight session network <session-id> --start <utc> --end <utc> --host <host> --json\n```\n\nBegin with high-signal filters, then widen severity, streams, sources, tags, status classes, or text only as needed. Include network bodies only when the request needs them and captured content is safe to inspect.\n\n### Telemetry\n\nRun the built-in detectors as leads:\n\n```sh\nansight session telemetry analyze <session-id> --kind all --json\n```\n\nUse `--kind fps-drop` or `--kind memory-spike` for a focused check. Threshold flags change detector sensitivity; they do not establish a product requirement. Use `--fail-on-detection` only when exit code `11` should mean a finding was detected.\n\nInspect channel metadata and samples:\n\n```sh\nansight session metrics <session-id> --json\nansight session metrics <session-id> --channel <channel-id> --limit <count> --json\n```\n\nThe metrics command selects by channel and newest-sample limit, not by time range. Choose a limit that includes the investigation interval, then filter and correlate the returned UTC sample timestamps. Never imply that `--limit` isolated a time window.\n\n### Visual And Interaction Evidence\n\n```sh\nansight session images <session-id> --json\nansight session trees <session-id> --json\nansight session touches <session-id> --json\n```\n\nJoin screenshots and visual trees through `screenshotFrameId` and nearby capture timestamps. Use touches to establish what input occurred, not whether the intended postcondition succeeded. Export one relevant frame when visual inspection is needed:\n\n```sh\nansight session screenshot export <session-id> --frame-id <frame-id> --output <path>\n```\n\n### App-Supplied Evidence\n\n```sh\nansight session artifacts <session-id> --json\nansight session artifact export <session-id> --snapshot-id <id> --path <artifact-path> --output <path>\n```\n\nInspect only artifacts relevant to the hypothesis. Preserve their snapshot ID, capture time, and path in the report.\n\n## Slice Evidence Safely\n\n| Need | Preferred action |\n| --- | --- |\n| Inspect a narrow log or network interval | Use `--start` and `--end`; do not create another session |\n| Correlate all evidence surfaces for a durable interval | Create a derived session with `session extract` |\n| Reuse an annotation's exact interval | Extract by annotation ID |\n| Remove evidence from the original session | Use `session trim` only with explicit authorization |\n\nCreate a non-destructive derived slice only when the user asks to retain, hand off, replay, or repeatedly inspect it:\n\n```sh\nansight session extract <session-id> --start <utc> --end <utc> --name <name> --json\nansight session extract <session-id> --annotation <annotation-id> --name <name> --json\n```\n\nThe new session is a separate local capture. Record its returned session ID. Do not call `session trim` during ordinary investigation: `cut` and `keep` mutate the existing session timeline.\n\n## Correlate Before Concluding\n\nFor each candidate explanation:\n\n1. Identify the earliest supporting event.\n2. Check what changed immediately before and after it across an independent surface when available.\n3. Distinguish correlation from causation.\n4. Check for contradictory evidence and normal control periods.\n5. State capture gaps, truncation, missing channels, sparse screenshots, or absent visual trees.\n\nPrefer runtime evidence over a source-only explanation. Read source after the observed behavior identifies a component, handler, request, or state transition to inspect.\n\n## Report A Reproducible Evidence Trail\n\nReport the selected session and why it matched; UTC interval and anchor; material commands and filters; timestamped observations with IDs; strongest supported explanation and confidence; contradictory or missing evidence; any derived slice and its session ID; and the smallest next verification step.\n\nDo not present detector output, an input attempt, or a single coincident log as proof by itself.\n"
}