ring-planning-frontend-refactor

name

ring:planning-frontend-refactor

description

Planning a frontend refactor: audits an existing React/Next.js frontend against Ring standards (architecture, design system, accessibility, testing) and produces a prioritized task list (findings.md + tasks.md) for ring:running-dev-cycle-frontend. Plans only — no edits. Use when an existing frontend needs to meet standards or an audit is requested. Skip for greenfield, single-file fixes, or backend (use ring:planning-backend-refactor).

Dev Refactor Frontend

When to use

• User wants to refactor existing frontend project to follow standards
• Legacy React/Next.js codebase needs modernization
• Frontend project audit requested

Skip when

• Greenfield project → Use /ring:planning-small-features or /ring:planning-large-features instead
• Single file fix → Use ring:running-dev-cycle-frontend directly
• Backend-only project → Use ring:planning-backend-refactor instead

Sequence

Runs before: ring:running-dev-cycle-frontend

Analyzes existing frontend codebase against Ring/Lerian standards and generates refactoring tasks for ring:running-dev-cycle-frontend.

You orchestrate. Agents analyze. NEVER use Bash/Grep/Read to analyze code — dispatch agents.

Gap Principle

Every divergence from Ring standards = a mandatory gap. No exceptions.

All divergences → FINDING-XXX → REFACTOR-XXX task → ring:running-dev-cycle-frontend input.

Architecture Pattern Applicability

Project Type	Apply Frontend Standards?
Full React/Next.js App	✅ YES — all frontend.md sections
Design System Library	✅ YES
Landing page / static	⚡ PARTIAL — directory + styling only
Utility / config package	❌ NO

Standards Loading

Pre-fetch before any step:

WebFetch: https://raw.githubusercontent.com/LerianStudio/ring/main/CLAUDE.md
WebFetch: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md
WebFetch: testing-accessibility.md, testing-visual.md, testing-e2e.md, testing-performance.md

STOP if any fetch fails.

Execution Steps

Step 1: Validate Prerequisites

• Check docs/PROJECT_RULES.md exists → STOP if missing
• Detect UI library mode: read package.json
  • @your-org/design-system → design-system
  • Otherwise → fallback-only
• If go.mod and no React → STOP: use ring:planning-backend-refactor

Step 2: Generate Codebase Report

Dispatch ring:codebase-explorer:

Generate comprehensive codebase report: project structure, React/Next.js patterns,
component architecture, state management, forms, styling, testing approach,
package.json dependencies. Output: docs/ring:planning-frontend-refactor/{timestamp}/codebase-report.md

Step 3: Dispatch Frontend Specialist Agents (parallel)

Verify codebase-report.md exists before dispatching.

Dispatch all 3 in ONE message:

Task 1: ring:frontend (MODE: ANALYSIS only)
  - Load frontend.md via WebFetch
  - Check all 19 sections per standards-coverage-table.md
  - Flag framework/library mismatches vs standards
  - File size enforcement: >1000 lines = ISSUE-XXX
  - UI Library Mode: {ui_library_mode}
  - Output: Standards Coverage Table + ISSUE-XXX per finding

Task 2: ring:qa-frontend (MODE: ANALYSIS only)
  - Check all 19 testing sections (ACC, VIS, E2E, PERF)
  - UI Library Mode: {ui_library_mode}
  - Output: Standards Coverage Table + ISSUE-XXX for gaps

Task 3: ring:ui-engineer (MODE: ANALYSIS only)
  - Check design system component usage compliance
  - If ui_library_mode = "fallback-only", check custom component WCAG 2.1 AA accessibility, responsive/layout fallback behavior, and design-token/theme fallback usage
  - For fallback-only mode, output ISSUE-XXX per violation plus a short note that frontend and qa-frontend own baseline implementation/testing coverage
  - Output: ISSUE-XXX for non-compliant usage

Step 4: Map Findings → Tasks

After all agents complete:

1. Save reports to docs/ring:planning-frontend-refactor/{timestamp}/
2. Map each ISSUE-XXX → FINDING-XXX
3. Generate findings.md
4. Map each FINDING-XXX → REFACTOR-XXX (1:1)
5. Generate tasks.md (ring:running-dev-cycle-frontend compatible)

Findings template:

## FINDING-001: {Pattern Name} in {file_path}
- **Severity:** CRITICAL | HIGH | MEDIUM | LOW
- **File:** {path}:{line}
- **Current:** {code or description}
- **Expected:** {Ring standard}

Step 5: Visual Report + User Approval

Generate visual HTML summary → ring:visualizing. Present to user. Wait for explicit APPROVED.

Step 6: Save + Handoff

Save all artifacts. Handoff to ring:running-dev-cycle-frontend.

Severity Reference

Severity	Criteria
CRITICAL	Security risk, WCAG legal issue, build broken
HIGH	Missing server components, Lighthouse < 80, wrong pattern
MEDIUM	Client component overuse, missing snapshots
LOW	Naming conventions, file organization