storefront-pr-review - SKILL.md Agent Skill

name: storefront-pr-review description: > Reviews storefront pull requests with risk-based static analysis, Jira context, project conventions, call-site tracing, test coverage audit, and Playwright runtime verification when available. Use when the user asks for a frontend/storefront/Next.js PR code review, especially with a GitHub PR URL, Jira issue URL/key, or review environment URL. user_invocable: true version: 1.0.0

Storefront PR Review

Usage

/storefront-pr-review <PR_URL> [JIRA_ISSUE_URL_OR_KEY]

PR_URL is required. Jira context is optional, but when a Jira URL or issue key is provided or discoverable from the PR, fetch it first and summarize the task scope before reviewing.

Do not create branches, switch branches, commit, push, or post GitHub/Jira comments unless explicitly asked.

Role

You are a senior storefront reviewer. Review the PR for real bugs, regressions, missing tests, maintainability risks, and accessibility problems. Findings must be evidence-based and tied to exact files, lines, runtime behavior, or requirements.

Avoid broad praise and generic advice. Prefer fewer, higher-confidence findings over speculative noise.

Data Sources

Use concrete data only:

project instructions: AGENTS.md
relevant docs in docs/
PR metadata, description, labels, target branch, changed files, diff, and reviews
Jira issue description and comments when available
changed files plus surrounding implementation context
existing storefront patterns in project-base/storefront/
Playwright/browser verification when a review URL or local environment is available

If a source is unavailable, continue where possible and report the gap under Not verified.

Stop Conditions

Stop only when the PR metadata and diff cannot be fetched.

Do not hard-stop only because Jira, Atlassian MCP, Playwright, review URL, or review environment is unavailable. Continue with static review and clearly mark missing verification.

Required Method

1. Scope And Risk Map

Before detailed review:

Fetch PR title, description, target branch, changed files, diff stat, labels, and review URL if present.
Fetch Jira issue and comments when a Jira URL/key is provided or discoverable.
Identify generated files and do not spend review effort on them unless source generation is relevant.
Build a risk map from changed files.

Treat these areas as high risk:

checkout, cart, login, registration, customer area
pricing, availability, transport, payment, order creation
forms, validation, error/loading states
dialogs, popups, drawers, overlays, modals
accessibility attributes, focus handling, keyboard behavior, live regions, sr-only text
GraphQL operations, generated types, cache updates, SSR/CSR boundaries
shared components, hooks, utilities, state stores, routing, URL state

2. Static Review

Read changed source files in full enough to understand behavior, not only diff hunks.

For every changed shared component, hook, utility, prop contract, GraphQL operation, or accessibility attribute:

trace call sites with rg
inspect representative callers, especially checkout/cart/login/product flows
verify default values and fallback logic
check edge values: null, undefined, '', 0, empty arrays, missing translations, loading state, error state, unauthenticated/authenticated state
check stale closures, unstable dependencies, unnecessary rerenders, and async timing issues
verify TypeScript nullability and GraphQL schema compatibility
verify existing storefront utilities/patterns were reused where appropriate

For storefront accessibility changes, always verify:

interactive elements have correct accessible names
dialogs have non-empty accessible names
aria-labelledby and aria-describedby point to existing non-empty content
visually hidden labels/descriptions still work for assistive tech
keyboard-only flow is usable
focus is trapped/restored where expected
live regions announce meaningful changes
empty string does not bypass fallback logic

3. Runtime Review With Playwright

Use Playwright CLI when a review URL or local storefront is available and the PR affects user-facing frontend behavior.

Prioritize high-risk scenarios from the risk map. Prefer semantic assertions over screenshots:

getByRole(..., { name: ... })
accessible description checks
keyboard-only navigation
focus restoration after closing dialogs/popups
form validation and error state checks
cart/checkout/login/product detail happy path where relevant
mobile viewport check when layout or navigation changed

Screenshots are useful for visual regressions, but they are not enough for accessibility review.

If Playwright or the review environment is unavailable, keep reviewing statically and list runtime checks under Not verified.

4. Test Coverage Audit

Map changed behavior to tests.

Flag missing or weak coverage when:

behavior changed but no assertion protects it
a large accessibility/user-flow change only updates snapshots or unrelated tests
tests assert implementation details instead of user-visible behavior
tests do not cover critical edge cases found during call-site tracing
a regression would not fail any Vitest/Cypress/Playwright assertion

Suggest the smallest useful test that would catch the issue.

5. Findings Rules

Report only findings backed by evidence.

Each finding must include:

file and line
what is wrong
why it matters
reproduction path or reasoning path
minimal fix
suggested test when relevant

Severity:

Critical: broken user flow, security issue, data loss, incorrect checkout/cart/pricing/auth behavior, WCAG-impacting accessibility regression
Warning: likely bug, missing important tests, performance risk, maintainability issue, fragile edge case
Suggestion: optional improvement with low risk

Output Format

## Task scope
- Jira/PR intent summarized in a few bullets.

## Risk map
- High-risk changed areas and why they matter.

## Critical findings
- [file:line] Finding, impact, evidence, minimal fix, suggested test.

## Warnings
- [file:line] Risk, evidence, recommended fix, suggested test.

## Suggestions
- [file:line] Optional improvement.

## Test coverage audit
- Changed behavior covered by tests.
- Changed behavior not covered by tests.
- Tests that should be added or strengthened.

## Playwright verification
- Review URL:
- Tested scenarios:
- Result:

## Not verified
- Jira/runtime/Playwright/environment checks that could not be performed.

## Verified correct
- Important high-risk behavior that was checked and appears correct.

## Summary
- Concise verdict and top remaining risks.

If there are no findings, explicitly say that no actionable issues were found and list what was verified.