git:20261022.4a60454 to git:20261022.3178d4a

---

name: jam-fix

description: Find the root cause of a bug from a Jam (a jam.dev bug recording with video, console and network), 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 bug report recorded in the browser or on a screen. It carries

the video or screenshot, console logs, network requests and user events of

the moment the bug happened. Its id is the UUID at the end of

`https://jam.dev/c/<id>`; every tool takes the full URL or the id.

## Pick the interface

Use the connected Jam 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 "<what you were doing, what you expected, what happened, the mistake>" --category <skills|mcp|cli|docs> --subject <skill name, tool name or command>

```

- 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.