--- name: jam-fix description: Find the root cause of a bug from a Jam (a jam.dev screen recording with the console, network and user actions attached), and fix it when the user asks. Without that ask it diagnoses only, with no code changes. Read the recording's diagnostics and visual evidence, then return a diagnosis with evidence. Use when the user pastes a jam.dev link or Jam id and asks to fix, debug, triage or investigate it, or asks what went wrong in a recording. --- # jam-fix One Jam in, one diagnosis out, plus the fix when the user asks for one. The diagnosis says what happened, the likely cause, the evidence for it, and what to do next. Stop reading data once you have the cause. A Jam is a recording of what happened on a screen: the video or screenshot with the console logs, network requests and user events of that moment attached. This skill reads one that shows a bug. Its id is the UUID at the end of `https://jam.dev/c/`; every tool takes the full URL or the id. ## Pick the interface Use the connected Jam Model Context Protocol (MCP) tools (`getDetails`, `getConsoleLogs`, ...). If a tool is unavailable, say what could not be read. Do not invent evidence. When MCP is unavailable and a shell is available, read [references/cli.md](references/cli.md) for Jam CLI setup and the command for each step below. That reference also covers optional proof uploads. ## 1. Read the report Call `getDetails`. Note: - what the reporter wrote, and the page URL - the type: `video`, `screenshot` or `replay`. It decides which visual tools work - browser, OS and screen size - the **Investigation Guide**, returned as the second text block. MCP only: the CLI has no guide, so from the CLI go straight to step 2 The guide is built from signals in this Jam (error counts, failing hosts, whether the mic was on). **Follow it before anything below.** Take its `high` priority paths first. The steps that follow are for when the guide is thin or you need to dig deeper. A fresh Jam may answer "not ready yet" from the event tools. It is still processing: wait a few seconds and retry, up to three times, then work from what is ready and say what was not. ## 2. Failed requests `getNetworkRequests` with `statusCode: ["4xx", "5xx"]`. Look for CORS errors, timeouts, auth failures, and response shapes the client did not expect. When a `200` returned the wrong data, ask for its body too. The tool description covers the filters, bodies and paging. ## 3. Console errors `getConsoleLogs` with `logLevel: ["error"]`. Look for unhandled exceptions and stack traces, and line their timestamps up with the failed requests. Network shows failures but the console is clean? The app may be swallowing errors. Read the console again with no `logLevel` filter. ## 4. What the user did `getUserEvents` gives clicks, inputs, navigation and scrolls in order. Find the action right before the first error. Repeated clicks or back-and-forth navigation mean the user was confused or the UI did not respond. ## 5. What was on screen Check the type from step 1 first; the video tools do not work on other types. - **Screenshot:** `getScreenshots`. - **Replay:** no frames or screenshots. Work from events, console and network. - **Video:** `getFrames` with `overview: true` for one labeled grid, then frames around the failure. - **Video with the mic on:** `getVideoTranscript` first. The reporter's own words are the cheapest signal of intent. - **Long video:** `getVideoChapters`, then frames from the chapter that matters. ## 6. App context `getMetadata` returns what the app sent with `jam.metadata()`: user id, feature flags, app version. Check it when the bug depends on who or which build. ## 7. Write the diagnosis ``` ## Summary One sentence: what broke, where. ## What happened The user's steps, ending at the failure. ## Root cause hypothesis The most likely technical cause. Name the file or endpoint when the code is open. ## Evidence - The request, console error or event that supports it, with its timestamp. ## Not checked - What you could not confirm, and why. ## Next steps 1. The fix or the next check. ``` If the repository is open, go from the evidence to the code: search for the failing endpoint, the error message, or the component on screen, and name the line you suspect. ## When the user asked for a fix 1. Diagnose first. Do not edit code until the evidence points at a cause. 2. Fix the cause, not the symptom the Jam shows. A swallowed error or a retry around a failing request is not a fix. 3. Verify against the Jam's steps: a failing test that now passes, or the steps run again against the fixed app. Say which, and what you saw. 4. Return the diagnosis, the change, and how you verified it. If the fix is unverified, say so. 5. Offer proof of the fix. The reported Jam is already the "before", so only the "after" needs a Jam. Offer it; do not create one without a yes. If no recording or upload tool is available, return the verification results and say that a new Jam could not be created. For approved proof uploads from a coding agent, use [the CLI proof instructions](references/cli.md#proof-of-a-fix). ## After Return the diagnosis and any fix in chat. If the user asked to post findings on the Jam, use `createComment` once with what you found or changed. Pin it to the moment with `playbackRelativeTimestamp` when relevant. Mention someone only when the user requested a mention. A diagnosis or fix request alone does not authorize comments, mentions, or posting to a PR or ticket. ## Send feedback to Jam When this skill, a Jam MCP tool, a `jam` command or a Jam doc was wrong, stale or confusing, or worked unusually well, tell Jam. Send it yourself: Jam's agents read it, so it needs no approval. Call the `submitFeedback` MCP tool with `body`, `category` and `subject`. When MCP is unavailable, use the CLI: ```bash jam feedback "" --category --subject ``` - Jam surfaces only, not the user's code or other tools. - At most once per session, and never for a slip you corrected yourself. - No secrets, customer data, source code, stack traces or recording content.