chromatic-workflow-debug

Stars0

Forks0

UpdatedApril 14, 2026 at 15:56

Diagnose Chromatic workflow issues involving git history, baselines, pull request event shape, merge queues, merge-base failures, replacement builds, and patch builds. Use when builds compare against the wrong baseline, an ancestor build is not found, pull request comparisons look wrong, or CI git context does not match Chromatic's expectations.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

chromaui

chromaui/chromatic-skills

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software Quality Assurance Analysts and TestersComputer and Mathematical Occupations·SOC 15-1253

File Explorer

22 files

SKILL.md

readonly

name	chromatic-workflow-debug
description	Diagnose Chromatic workflow issues involving git history, baselines, pull request event shape, merge queues, merge-base failures, replacement builds, and patch builds. Use when builds compare against the wrong baseline, an ancestor build is not found, pull request comparisons look wrong, or CI git context does not match Chromatic's expectations.
metadata	{"short-description":"Diagnose Chromatic git and baseline workflow issues"}

Workflow Debug

Public-safe skill for debugging how Chromatic maps CI, git history, and prior builds into comparisons and baselines.

This package is the single source of truth for:

workflow diagnosis codes
the evidence ladder
the command catalog
the diagnosis card output contract
documentation topic mapping
copy-paste intake prompts
public-safe examples and evaluations

Quick start

Read reference/workflow-playbook.md and identify the current workflow phase.
Read reference/diagnosis-taxonomy.md and choose the strongest diagnosis code the evidence supports.
Read reference/evidence-ladder.md and decide whether you can answer now or need one more artifact.
Use reference/command-catalog.md only when the current evidence is insufficient.
Render the result with reference/output-contract.md.
If the user wants follow-up reading, use the topic map in reference/docs-map.md.

Required workflow

1) Start with current evidence

Prefer evidence already provided:

the exact Chromatic command or GitHub Action step
the relevant warning or error text
CI event type and branch information
git checkout settings such as shallow history or detached HEAD
build URL and the expected comparison target
any manual overrides like branchName, repositorySlug, patchBuild, or ignoreLastBuildOnBranch

Do not ask for a broad dump if the current evidence already points to one branch of the decision tree.

2) Classify before proposing changes

Choose one primary workflow diagnosis code from reference/diagnosis-taxonomy.md.

If multiple signals exist, prioritize:

incorrect or missing git history over downstream symptoms
wrong CI branch or PR event shape over later baseline confusion
merge-base or patch-build failures over generic comparison complaints
replacement-build and rebase behavior over speculative Storybook causes

3) Ask for the smallest next artifact

Ask for exactly one next artifact or one targeted command result.

Typical next artifacts:

the exact actions/checkout step or equivalent CI checkout snippet
the exact Chromatic invocation line or action inputs
git branch --show-current
git rev-parse HEAD
git log --oneline --decorate -n 10
git merge-base <head> <base>
the specific Chromatic warning mentioning baselines, merge base, or no ancestor build

Do not jump straight to Storybook flags or TurboSnap suppression flags unless the workflow evidence already cleared the git branch.

4) Stay truthful about the current run

If the current run cannot compute the intended comparison safely, say so plainly.

Examples:

a shallow checkout means the current run cannot reason about baselines correctly
a pull_request merge commit can point Chromatic at the wrong SHA or branch unless the action passes the correct values
a rebased branch may need ignoreLastBuildOnBranch or a fresh baseline path
a missing merge base means a patch build path is needed, not a baseline guess

5) Output a diagnosis card every time

Always return the diagnosis card from reference/output-contract.md.

If confidence is still low:

name the most likely diagnosis
say why confidence is limited
request one exact next artifact or command
avoid speculative repo surgery

Boundaries

Keep the skill public-safe and customer-safe.
Ask for one artifact at a time.
Do not rely on live external documentation inside the installed skill.
Do not recommend unrelated monorepo flags as a first response to git or baseline problems.
Do not assume the customer is using GitHub Actions unless the evidence says so, but prefer GitHub Actions examples when you need a concrete pattern.

References and examples

reference/workflow-playbook.md
reference/diagnosis-taxonomy.md
reference/evidence-ladder.md
reference/command-catalog.md
reference/output-contract.md
reference/docs-map.md
template.md
examples/pr-merge-commit.md
examples/rebase-replacement-build.md
evaluations/README.md

More from this repository

same repository

chromatic-troubleshoot-config

chromaui/chromatic-skills

Diagnose Storybook configuration issues that block Chromatic or local Storybook, including missing stories, framework or builder mismatches, addon conflicts, preview errors, static asset path issues, and package version drift. Use when Storybook fails to build, Chromatic cannot verify Storybook, stories are missing, or a team needs the smallest config change to restore a working Storybook surface.

2026-04-230

chromatic-troubleshoot-diff

chromaui/chromatic-skills

Diagnose unexpected Chromatic visual diffs, snapshot inconsistencies, font and resource loading drift, animation timing issues, viewport or globals mismatches, sticky or fixed positioning quirks, and nondeterministic story output. Use when snapshots change unexpectedly or the same code produces inconsistent diffs and you need the narrowest next step to stabilize the snapshot.

2026-04-230

chromatic-themes

chromaui/chromatic-skills

Configure Chromatic to capture visual test snapshots across multiple themes (light/dark mode, design tokens, branded variants) using the Modes API and @storybook/addon-themes. Use when the user wants to test components with different themes in Chromatic, set up light/dark mode visual testing, configure @storybook/addon-themes with Chromatic, or apply theme modes at the project, component, or story level.

2026-04-140

chromatic-viewports

chromaui/chromatic-skills

Configure Chromatic to capture visual test snapshots at multiple viewport sizes using the Modes API. Use when the user wants to test responsive components at different screen sizes, set up viewport breakpoints for Chromatic visual testing, apply viewports to individual stories or globally, control snapshot height with cropToViewport, or migrate from the legacy chromatic.viewports API to the new Modes API.

2026-04-140

chromatic-monorepo-config

chromaui/chromatic-skills

Recommend Chromatic best practices for Nx and Turborepo monorepos, including one-project versus multi-project topology, workingDir, buildCommand or outputDir, storybookBaseDir, storybookConfigDir, onlyChanged, externals, untraced, shared lockfile behavior, and TurboSnap-safe CI patterns. Use when a monorepo needs an initial setup recommendation or an audit of an existing Chromatic configuration.

2026-04-140

chromatic-turbosnap-debug

chromaui/chromatic-skills

Diagnose TurboSnap behavior using logs, config, git context, support-shareable hosted metadata references, and targeted trace commands. Use when you need to classify why TurboSnap is enabled, disabled, unavailable, or tracing the wrong stories, then recommend the smallest valid next step.

2026-04-140

name	chromatic-workflow-debug
description	Diagnose Chromatic workflow issues involving git history, baselines, pull request event shape, merge queues, merge-base failures, replacement builds, and patch builds. Use when builds compare against the wrong baseline, an ancestor build is not found, pull request comparisons look wrong, or CI git context does not match Chromatic's expectations.
metadata	{"short-description":"Diagnose Chromatic git and baseline workflow issues"}

Workflow Debug

Public-safe skill for debugging how Chromatic maps CI, git history, and prior builds into comparisons and baselines.

This package is the single source of truth for:

workflow diagnosis codes
the evidence ladder
the command catalog
the diagnosis card output contract
documentation topic mapping
copy-paste intake prompts
public-safe examples and evaluations

Quick start

Read reference/workflow-playbook.md and identify the current workflow phase.
Read reference/diagnosis-taxonomy.md and choose the strongest diagnosis code the evidence supports.
Read reference/evidence-ladder.md and decide whether you can answer now or need one more artifact.
Use reference/command-catalog.md only when the current evidence is insufficient.
Render the result with reference/output-contract.md.
If the user wants follow-up reading, use the topic map in reference/docs-map.md.

Required workflow

1) Start with current evidence

Prefer evidence already provided:

the exact Chromatic command or GitHub Action step
the relevant warning or error text
CI event type and branch information
git checkout settings such as shallow history or detached HEAD
build URL and the expected comparison target
any manual overrides like branchName, repositorySlug, patchBuild, or ignoreLastBuildOnBranch

Do not ask for a broad dump if the current evidence already points to one branch of the decision tree.

2) Classify before proposing changes

Choose one primary workflow diagnosis code from reference/diagnosis-taxonomy.md.

If multiple signals exist, prioritize:

incorrect or missing git history over downstream symptoms
wrong CI branch or PR event shape over later baseline confusion
merge-base or patch-build failures over generic comparison complaints
replacement-build and rebase behavior over speculative Storybook causes

3) Ask for the smallest next artifact

Ask for exactly one next artifact or one targeted command result.

Typical next artifacts:

the exact actions/checkout step or equivalent CI checkout snippet
the exact Chromatic invocation line or action inputs
git branch --show-current
git rev-parse HEAD
git log --oneline --decorate -n 10
git merge-base <head> <base>
the specific Chromatic warning mentioning baselines, merge base, or no ancestor build

Do not jump straight to Storybook flags or TurboSnap suppression flags unless the workflow evidence already cleared the git branch.

4) Stay truthful about the current run

If the current run cannot compute the intended comparison safely, say so plainly.

Examples:

a shallow checkout means the current run cannot reason about baselines correctly
a pull_request merge commit can point Chromatic at the wrong SHA or branch unless the action passes the correct values
a rebased branch may need ignoreLastBuildOnBranch or a fresh baseline path
a missing merge base means a patch build path is needed, not a baseline guess

5) Output a diagnosis card every time

Always return the diagnosis card from reference/output-contract.md.

If confidence is still low:

name the most likely diagnosis
say why confidence is limited
request one exact next artifact or command
avoid speculative repo surgery

Boundaries

Keep the skill public-safe and customer-safe.
Ask for one artifact at a time.
Do not rely on live external documentation inside the installed skill.
Do not recommend unrelated monorepo flags as a first response to git or baseline problems.
Do not assume the customer is using GitHub Actions unless the evidence says so, but prefer GitHub Actions examples when you need a concrete pattern.

References and examples

reference/workflow-playbook.md
reference/diagnosis-taxonomy.md
reference/evidence-ladder.md
reference/command-catalog.md
reference/output-contract.md
reference/docs-map.md
template.md
examples/pr-merge-commit.md
examples/rebase-replacement-build.md
evaluations/README.md