# Session Debug

> Diagnose issues in the current Amplifier session — misconfigured tools, failing operations, unexpected behavior. Use when something isn't working right.

- Skill: `microsoft/session-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add microsoft/session-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/session-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/session-debug

---


# Debug: Session Diagnostics

Help the user diagnose an issue they're encountering in their current Amplifier session.

## Issue Description

$ARGUMENTS

If no issue was described, read the session logs and summarize any errors, warnings, or notable issues.

## Instructions

1. **Delegate to the session-analyst agent** to investigate the current session. The session-analyst has specialized knowledge for safely analyzing large event logs (events.jsonl files can contain lines with 100k+ tokens that will crash other tools). Use the delegate tool to dispatch it with the issue description and any relevant context.

2. **Check session configuration.** Review the current session's configuration for common issues:
   - Bundle composition problems (missing modules, failed loads)
   - Provider configuration (missing API keys, wrong endpoints)
   - Tool availability (tools expected but not mounted)
   - Hook failures (hooks that errored during lifecycle events)

   Session and project settings are typically at:
   - Project: `.amplifier/settings.yaml`
   - User: `~/.amplifier/settings.yaml`
   - Keys: `~/.amplifier/keys.env`

3. **Check for common patterns:**
   - Tool calls returning errors repeatedly
   - Provider rejections (rate limits, auth failures, model not found)
   - Module mount failures at startup
   - Context overflow or compaction issues

4. **Explain what you found in plain language.** Avoid jargon. Tell the user:
   - What went wrong
   - Why it likely happened
   - Concrete steps to fix it

5. **If the issue can't be diagnosed from logs alone**, suggest the user:
   - Run `amplifier doctor` for a system health check
   - Check `amplifier module list` to verify module availability
   - Try `amplifier --verbose` to see detailed startup output