Troubleshoot

Purpose

This skill investigates and explains unexpected chat agent behavior using direct log files.

Use this skill for questions like:

• Why did this request take so long?
• Why was a tool or subagent called?
• Why did instruction/skill/agent files not load?
• Why was a tool call blocked or failed?
• Why did the model not follow expectations?

Base conclusions on evidence from logs. Do not guess.

Data Source

• Target session log directory/directories for analysis: {{VSCODE_TARGET_SESSION_LOG}}

Use direct debug log files written by Copilot Chat:

debug-logs/<sessionId>/
  main.jsonl                              — always start here; primary conversation log
  models.json                             — (optional) snapshot of available models at session start
  system_prompt_0.json                    — (optional) full system prompt sent to the model (untruncated)
  system_prompt_1.json                    — (optional) written when the model changes mid-session
  tools_0.json                            — (optional) tool definitions sent to the model
  tools_1.json                            — (optional) written when the model changes mid-session
  runSubagent-<agentName>-<uuid>.jsonl    — (optional) subagent's tool calls & LLM requests
  searchSubagent-<uuid>.jsonl             — (optional) search subagent work
  title-<uuid>.jsonl                      — (optional, UI-only) title generation
  categorization-<uuid>.jsonl             — (optional, UI-only) prompt categorization
  summarize-<uuid>.jsonl                  — (optional, UI-only) conversation summarization

Always read main.jsonl first — it has the full conversation flow. Child files only appear when those operations occurred. main.jsonl contains child_session_ref entries that link to each child file by name. Title, categorization, and summarize files are UI housekeeping and rarely relevant to troubleshooting. When investigating model availability or selection issues, read models.json — it contains the full list of models (with capabilities, billing, and limits) that were available when the session started.

When investigating what the model was told (system prompt, instructions), read the system_prompt_*.json file referenced by a system_prompt_ref entry in main.jsonl. The file contains the full untruncated system prompt as { "content": "..." }. When investigating which tools were available, read the tools_*.json file similarly. If the model changed mid-session, multiple numbered files exist — each llm_request entry has a systemPromptFile attr indicating which file was active for that request.

Each line is a JSON object. Common fields: ts (epoch ms), dur (duration ms), sid (session ID), type, name, spanId, parentSpanId, status (ok|error), attrs (type-specific details).

Event Type Reference with Examples

discovery — customization file loading (instructions, skills, agents, hooks)

{"ts":1773200251309,"dur":0,"sid":"62f52dec","type":"discovery","name":"Load Instructions","spanId":"2cb1f2f4","status":"ok","attrs":{"details":"Resolved 0 instructions in 0.0ms | folders: [/c:/Users/user/.copilot/instructions, /workspace/.github/instructions]","category":"discovery","source":"core"}}
{"ts":1773200251415,"dur":0,"sid":"62f52dec","type":"discovery","name":"Load Agents","spanId":"38a897d8","status":"ok","attrs":{"details":"Resolved 3 agents in 0.0ms | loaded: [Plan, Ask, Explore] | folders: [/workspace/.github/agents]","category":"discovery","source":"core"}}
{"ts":1773200251431,"dur":0,"sid":"62f52dec","type":"discovery","name":"Load Skills","spanId":"472eb225","status":"ok","attrs":{"details":"Resolved 6 skills in 0.0ms | loaded: [agent-customization, troubleshoot, ...]","category":"discovery","source":"core"}}

Key attrs: details (human-readable summary with folder paths, loaded items, skip reasons), category (always "discovery"), source ("core").

…