SYSTEM REQUIREMENTS

Before execution the agent MUST load: .claude/protocols/gardener.md

CI Mode prerequisite: If running in CI, GITHUB_TOKEN must be exported with pull-requests: write permissions.

/frontend-code-review — Frontend Code Review

Verbosity Protocol (SILENT MODE)

• Do NOT output per-phase progress to chat.
• Do NOT print intermediate grep results or file lists to chat.
• Output to chat ONLY: blocker messages and the final SKILL COMPLETE block.

When to Use

• Review a PR before merge
• Review local staged/unstaged changes before committing
• CI-triggered review on pull request events

When NOT to Use

• Reviewing artifacts generated by /component-gen or /api-bind — use Auditor agent
• Full repository analysis — use /fe-repo-scout
• Specification review — use /spec-audit

Input

Usage: /frontend-code-review [target]

Targets:
  <pr-number>     Review a GitHub PR (e.g., 42)
  <branch>        Review diff of branch against main
  --staged        Review staged changes only
  (no argument)   Review diff of current branch against main

Protocol (BANNED)

• BANNED: commenting on code formatting or style (linter handles this)
• BANNED: suggesting full rewrites of unchanged code
• BANNED: hallucinating code that does not exist in the diff
• BANNED: flagging issues already covered by Biome/ESLint rules
• BANNED: reviewing non-frontend files (Go, Python, SQL, Dockerfile) unless they contain secrets
• BANNED: outputting intermediate grep/diff results to chat

Phase 1 — Context Discovery

1.1 Obtain Diff

# PR mode
git diff origin/main...HEAD -- '*.ts' '*.tsx' '*.vue' '*.js' '*.jsx' '*.css' '*.json'

# --staged mode
git diff --staged -- '*.ts' '*.tsx' '*.vue' '*.js' '*.jsx' '*.css' '*.json'

# PR number mode (gh pr diff does not support -- path filters;
# pipe output through grep or parse changed filenames to filter to frontend extensions)
gh pr diff <number>

If diff is empty after filtering → output ⚠️ No frontend files in diff and STOP.

1.2 Classify Changed Files

Group files by FSD layer (if applicable):

1.3 Detect Framework

Scan diff file extensions:

• .tsx / .jsx → React
• .vue → Vue
• Mixed → both (run framework-specific checks for each)

If unclear — read package.json for react or vue dependency.

1.4 Read Project Context

Read CLAUDE.md for project-specific conventions and banned patterns.

1.5 Diff Size Guard

git diff origin/main...HEAD --stat | tail -1

If diff exceeds 2000 added lines → review only CRITICAL and HIGH categories (Phases 2 and 3). Skip Phase 4. Note truncation in report.

Phase 2 — Security Scan

Reference: references/security-checklist.md

Scan added lines only (+ lines in diff) for each category in the security checklist.

For each finding, record:

• File path and line number
• Pattern matched
• Severity (CRITICAL / HIGH / MEDIUM)
• Recommendation

Scope rule: Only flag patterns in changed lines. Do not scan unchanged context lines.

Config & Dependency Review (conditional)

Run only if package.json or config files are in the diff:

• New dependencies: check for known vulnerable or deprecated packages
• Removed security headers or CSP rules
• Changed API base URLs or CORS configuration
• TypeScript strict mode disabled or loosened

Phase 2b — React Doctor Scan [React only]

If React detected in Phase 1.3:

1. Run npx react-doctor@latest . --diff origin/main --score 2>&1
2. Map findings: error → HIGH, warning → MEDIUM
3. Deduplicate with Phase 3 anti-pattern results (skip findings already covered)
4. Include health score in report header
5. If React Doctor unavailable → skip with note React Doctor not available — skipping Phase 2b

Reference: .claude/skills/react-doctor/references/antipattern-map.md for rule→anti-pattern mapping.

Phase 3 — Architecture & Anti-patterns

3.1 FSD Import Violations

For each changed file, verify import paths respect FSD layer hierarchy:

shared → entities → features → widgets → pages → app
(lower)                                        (higher)

VIOLATION: importing from a higher or same layer

For each changed file classified in Phase 1.2, use the Grep tool to search for imports from higher or same-level layers. Example: for files in src/entities/, search for from.*features/, from.*widgets/, from.*pages/.

3.2 Anti-pattern Scan

Lazy Load Protocol: Read .claude/fe-antipatterns/_index.md for grep signatures. Read individual pattern files ONLY when a violation is found in the diff.

Load references/antipattern-scan.md for pattern tables with grep signatures (Common, React-gated, Vue-gated).

3.3 Async State Completeness

For each new or modified component that uses data fetching (useQuery, useSWR, useMutation, fetch, axios):

Verify presence of all 4 states:

• Loading state (isLoading, isPending, skeleton, spinner)
• Error state (isError, error, error boundary)
• Empty state (empty array/null check)
• Success state (data rendering)

Missing states → HIGH finding.

Phase 4 — Performance & A11y Spot-Check

Performance

A11y Spot-Check

Phase 5 — Report Generation

Local Mode (default)

Generate report using template: references/review-report-template.md

Save to: audit/frontend-code-review_{YYYYMMDD_HHMMSS}.md

CI Mode (GitHub Actions)

When running in CI (environment variable CI=true or GITHUB_ACTIONS=true):

1. Post inline PR comments for CRITICAL and HIGH findings:

gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  --method POST \
  -f body="..." \
  -f commit_id="..." \
  -f path="..." \
  -F line=<number> \
  -f side="RIGHT"

1. Post summary comment on PR with finding counts and top issues.

Severity Classification

Quality Gate

Before marking SKILL COMPLETE, verify ALL of the following:

• Diff obtained and filtered to frontend files only
• Framework detected (not guessed)
• Security scan completed against references/security-checklist.md
• FSD import violations checked (if FSD structure detected)
• Anti-pattern scan used correct framework gate (React/Vue/both)
• No intermediate output printed to chat (SILENT MODE enforced)
• Report written to audit/ (local) or PR comments posted (CI)

Gardener Protocol

Call .claude/protocols/gardener.md before SKILL COMPLETE.

Markdown skills (append to artifact): frontend-code-review

Completion Contract

SKILL COMPLETE: /frontend-code-review
 - Report: audit/frontend-code-review_{YYYYMMDD_HHMMSS}.md
 - Framework: [detected]
 - Diff: [N files changed, +X/-Y lines]
 - Findings: [N critical / N high / N medium]
 - Top issues: [list]

SKILL PARTIAL: /frontend-code-review
 - Framework: [detected]
 - Artifacts: [list]
 - Coverage: [phases completed / total]
 - Blockers: [description]