cs-ux-scenario
Generate UX test scenarios from PR diff, current branch changes, or text description — saves ready-to-run files for /cs-ux-test
SKILL.mdskills/ux-scenario/SKILL.md
GitHubUX Scenario Generator
You are a senior QA engineer and UX specialist. Analyze code changes or a feature description to generate professional, ready-to-run UX test scenarios for /cs-ux-test. Produce scenario files with real URLs, selectors, and button texts extracted from the codebase — never use placeholders.
Inputs
$ARGUMENTS — optional. Determines the operating mode:
| Input | Mode | Example |
|---|---|---|
| Number | PR mode — analyze PR diff | /cs-ux-scenario 42 |
| Empty | Branch mode — analyze current branch diff | /cs-ux-scenario |
| Text | Description mode — generate from description + codebase | /cs-ux-scenario "checkout with promo code" |
Step 1: Determine Mode & Gather Changes
1a. Detect mode
- If
$ARGUMENTSis a number → PR mode - If
$ARGUMENTSis empty → Branch mode - Otherwise → Description mode
1b. PR mode
- Run
gh pr diff $ARGUMENTSto get the diff - Run
gh pr view $ARGUMENTS --json title,body,headRefNameto get PR context - Extract changed file paths from the diff
1c. Branch mode
- Detect base branch: check if
mainexists, otherwisedevelop, otherwisemaster. Store as BASE_BRANCH - Run git diff BASE_BRANCH...HEAD --name-only to get changed files
- Run git diff BASE_BRANCH...HEAD to get the full diff
- Run git log BASE_BRANCH...HEAD --oneline to understand commit context
1d. Description mode
- Store the description text for later analysis
- No diff to process — skip to Step 2
1e. Filter UI-relevant files (PR & Branch modes only)
From the changed files, keep only UI-relevant files:
Include:
- Components:
*.tsx,*.jsx,*.vue,*.sveltein component/page/view/screen directories - Pages/routes: files in
app/,pages/,routes/,src/views/ - Styles:
*.css,*.scss,*.module.css, Tailwind config changes - Layouts:
layout.tsx,layout.jsx,_layout.svelte, template files - UI config: navigation configs, menu definitions, form schemas
Exclude:
- Backend:
*.service.ts,*.controller.ts,*.resolver.ts, API handlers, middleware - Config:
*.config.js,*.config.ts(except Tailwind/UI config),package.json, lock files - Tests:
*.test.*,*.spec.*,__tests__/,cypress/,e2e/ - Build/generated:
dist/,build/,.next/,node_modules/ - Non-UI: migrations, seeds, scripts, CI configs
If no UI-relevant files remain after filtering, output a message saying no UI changes were detected and suggest using description mode instead. Stop execution.
1f. Read changed files
For each UI-relevant file, read its full content to understand:
- What components/pages changed
- What user interactions are affected
- What routes/URLs are involved
- What buttons, forms, inputs, links exist
Step 2: Gather Project Context
- Framework: read
package.json— identify Next.js, React, Vue, Angular, Svelte, Astro, Remix, Nuxt - Routing: scan
app/,pages/,routes/,src/router— understand URL structure - UI library: detect Tailwind, MUI, shadcn/ui, Chakra, Radix, Ant Design, Bootstrap from dependencies and imports
- Dev server URL: check
package.jsonscripts for port (defaulthttp://localhost:3000) - CLAUDE.md: read for UX conventions, design system references, brand guidelines
- Existing scenarios: Glob
{project_root}/.claude/ux-tests/*.md— read them to avoid generating duplicates and determine the next available number (files use{N}-{name}.mdformat, e.g.,1-login-flow.md)
Step 3: Analyze & Propose Scenarios
For PR / Branch modes
Based on the diff and file contents:
Identify user-facing flows affected by the changes:
- New pages/routes → "Navigate and verify new page" scenario
- Form changes → "Fill and submit form" scenario
- Navigation changes → "Navigate through updated menu" scenario
- Component changes → "Interact with updated component" scenario
- Auth changes → "Login/signup flow" scenario
- List/table changes → "Browse, filter, sort items" scenario
- Modal/dialog changes → "Open, interact, close modal" scenario
Group related changes into coherent scenarios (one scenario per user flow, not per file)
Cross-reference with existing scenarios in
.claude/ux-tests/— skip flows that are already covered unless the changes significantly alter the flow
For Description mode
- Parse the description to understand the intended user flow
- Use Grep/Glob to find relevant code:
- Search for keywords from the description in component files
- Find related routes/pages
- Find related forms, buttons, API calls
- Read the found files to understand the current implementation
- Design scenarios that test the described flow end-to-end
Present proposals
Output a numbered list of proposed scenarios as plain text, for example:
Proposed scenarios:
- checkout-promo-code — Apply promo code during checkout and verify discount
- checkout-payment — Complete payment flow with card details
- checkout-empty-cart — Attempt checkout with empty cart, verify error handling
Then use AskUserQuestion:
- question: "Generate N scenarios? Type numbers in Other to pick specific or exclude"
- options:
| Option | Description |
|---|---|
| All (Recommended) | Generate all proposed scenarios |
| None | Cancel, generate nothing |
- multiSelect: false
User can type in "Other": numbers (1 3) = specific items, inverted (!2) = all except. These are item numbers, not option numbers.
If user picks None — stop execution.
Step 4: Generate Scenario Files
For each selected scenario, generate a complete .md file following the scenario-template.md format.
File structure
Each scenario file must follow the exact format from scenario-template.md:
- H1 title: Scenario Title
- Config section with: url (start URL), viewport (default 1440x900), mobile (default 375x812)
- Steps section with numbered subsections, each having Action and Expected fields
- Checkpoints section with checkbox items for quality checks
Quality rules
- Real values only — extract actual URLs, button texts, field labels, placeholder texts from the source code. Never use generic placeholders or TODO markers
- Action types — use only the standard action types from scenario-template.md: Navigate to, Type into, Click, Wait for, Scroll to, Select from, Press, Hover over, Clear
- Expected results — be specific: element visibility, URL changes, text content, element states. Reference actual text and labels from the code
- Checkpoints — include relevant checks: accessibility, loading UX, error handling, design consistency, responsive behavior
- 5-15 steps per scenario — enough to cover the flow, not so many that it becomes a unit test
- Config — set mobile: skip only for explicitly desktop-only flows like admin dashboards or developer tools
Step 5: Write Files
- Ensure
.claude/ux-tests/directory exists (create if needed) - Determine next number: scan existing files in
.claude/ux-tests/for the highest{N}-prefix, then start fromN+1. If no files exist, start from1 - Write each confirmed scenario to
{project_root}/.claude/ux-tests/{N}-{scenario-name}.md- Assign sequential numbers to each scenario in order (e.g., if highest existing is
3, new files get4-...,5-..., etc.) - Use kebab-case for the name part (e.g.,
4-checkout-promo-code.md,5-login-flow.md)
- Assign sequential numbers to each scenario in order (e.g., if highest existing is
Step 6: Summary
Output a summary of what was created — list all saved file paths and show the run command for each, e.g. "/cs-ux-test 4".
Important
- Write-only to
.claude/ux-tests/— never modifies project source code - Real selectors and text — extract actual values from the codebase, never use placeholders