Troubleshoot Diff

Diagnose why a Chromatic snapshot changed and identify the narrowest stabilizing fix.

Required workflow

1. Start with current evidence. Prefer the build URL or build number, affected story, screenshot or diff description, local Storybook repro signal, active Chromatic params or globals, and any recent changes to fonts, assets, animations, viewports, decorators, or shared preview code. If the issue already points to a likely branch, do not ask for a broad repo dump.
2. Classify the issue using reference/diagnosis-taxonomy.md. Use reference/workflow-playbook.md when the branch is unclear. Prioritize local rendering problems before Chromatic-only theories, and treat intentional UI changes as expected diffs rather than stabilization work.
3. Read the mapped local source notes from reference/docs-map.md and reference/source-pack/README.md. Ground the fix path in those notes when they clearly apply.
4. Inspect the repo before asking for more data when the repo is available. Use reference/command-catalog.md; check the story, .storybook/preview.*, .storybook/preview-head.html, and relevant asset, mode, animation, and layout surfaces. If Playwright is available and helps settle the branch, reproduce there too.
5. If still blocked, ask for one exact artifact using reference/evidence-ladder.md. Prefer rerun-build or trace-viewer evidence when the issue is inconsistent across runs.
6. Return the diagnosis card from reference/output-contract.md. If confidence is still low, name the most likely diagnosis, say why confidence is limited, and request one exact next artifact or repo check.

Boundaries

• Ask for one artifact at a time.
• Do not recommend diffThreshold, snapshot ignores, or broad suppression as the first response to unexplained diffs.
• Do not claim Chromatic is the root cause when the same issue is already visible in local Storybook.
• Use the local source pack when it clearly applies instead of giving generic advice.
• Do not ask for the entire repository, all screenshots, or long CI logs when one story-level artifact would settle the branch.

References and examples

• reference/workflow-playbook.md
• reference/diagnosis-taxonomy.md
• reference/docs-map.md
• reference/evidence-ladder.md
• reference/command-catalog.md
• reference/output-contract.md
• reference/source-pack/README.md
• template.md
• evaluations/README.md