Terminal
Terminal/Skill
Finds Amplitude session replays where a bug happened and turns them into numbered steps to reproduce it.
By Amplitude
Works with
npx skills add amplitude/mcp-marketplace --skill debug-replayInvestigate bugs by finding session replays where the error occurred, extracting the interaction timeline, and distilling it into numbered reproduction steps an engineer can follow. This skill bridges the gap between "a user reported a bug" and "here's exactly how to reproduce it."
This skill operates on three Amplitude Session Replay tools. Use them in this order:
Amplitude:get_amp_session_replay_info with action: "search" — Find sessions matching event filters (errors, specific users, time windows). Returns session metadata and replay links.Amplitude:get_amp_session_replay_info with action: "list" — Simple paginated listing when you already have a user/device ID or just need recent sessions. Returns a session replay ID in device_id/session_id format.Amplitude:get_amp_session_replay_info with action: "events" — Decode a specific replay into an interaction timeline: navigations, clicks, inputs, scrolls. Pass the ID from the tools above as sessionReplayId.Supporting tools used in this skill:
Amplitude:use_amplitude_cohorts with action: "find" — Look up users by email, user ID, or other identifiers.Amplitude:use_amp_flags with action: "list_deployments" — Check if error aligns with a recent deploy.Parse the user's request to extract:
[Amplitude] Error Logged, a custom error event)If the report is vague (e.g., "something is broken in checkout"), ask one clarifying question before proceeding. Do not ask more than one.
Amplitude:get_amplitude_context. If multiple projects, ask which to investigate.[Amplitude] Error Logged — auto-captured JS errors[Amplitude] Network Request with status code filters — API failuresAmplitude:use_amplitude_cohorts with action: "find" to look up the user and get their user ID and device ID.Use Amplitude:get_amp_session_replay_info with action: "search" to find sessions where the error occurred. Build filters based on what you know:
If you have a specific user:
{
"action": "search",
"projectId": "12345",
"userProperties": [{"name": "gp:email", "is": "user@example.com"}],
"events": [{"name": "[Amplitude] Error Logged"}],
"limit": 5
}
If you have an error message but no specific user:
{
"action": "search",
"projectId": "12345",
"events": [
{
"name": "[Amplitude] Error Logged",
"withProperty": {"name": "Error Message", "contains": "TypeError"}
}
],
"limit": 5
}
Request 3-5 sessions. More sessions give better pattern extraction; fewer saves context.
For each session found in Step 3, call Amplitude:get_amp_session_replay_info with action: "events" and the sessionReplayId.
event_limit: 500 for standard sessionsevent_limit: 200 if analyzing 4+ sessions (to manage context)What to capture from each timeline:
This is the core analytical step. Compare the timelines from multiple sessions to find the common prefix — the shared sequence of actions that precedes the error.
If only 1 session is available, extract the timeline as-is and note that it hasn't been validated across multiple sessions.
Call Amplitude:use_amp_flags with action: "list_deployments" once. If an error spike aligns with a recent deploy, note it — this is critical context for the engineer.
Structure the output as an engineering-ready bug report.
Required sections:
Bug Summary (1-2 sentences): What's broken, who's affected, since when. Written as a headline an engineer would put in a ticket title.
Environment Context:
Reproduction Steps — Numbered, specific, copy-paste-ready:
## Reproduction Steps
1. Navigate to [URL]
2. Click [element/area description] at [approximate location]
3. Enter "[value]" in [field description]
4. Click [element/area description]
5. Observe: [error behavior — what the user sees]
**Expected:** [what should happen]
**Actual:** [what happens instead]
Error Context (if available):
Session Evidence:
Observations (optional): Patterns that may help debugging — rage clicks suggesting UI unresponsiveness, long pauses suggesting loading issues, specific input values that trigger the error.
use_amplitude_cohorts with action: "find" returns nothing, try searching with alternative identifiers (email domain, partial match). If still nothing, proceed without user filtering and search by error event alone.get_amp_session_replay_info with action: "events" returns DOM node IDs, not element names. Describe interactions by position (x, y coordinates), page context, and sequence rather than element identity. Use phrasing like "click in the upper-right area of the form" rather than "click the Submit button" unless you can infer from context.User says: "Customer jane@acme.com says the export button doesn't work"
Actions:
use_amplitude_cohorts with action: "find"get_amp_session_replay_info action: "search" filtered to her email + any error eventsUser says: "TypeError errors doubled yesterday, can you get repro steps?"
Actions:
[Amplitude] Error Logged existsget_amp_session_replay_info action: "search"User says: "Users are having trouble with checkout"
Actions: