| 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:
Step 4: Map Findings → Tasks
After all agents complete:
- Save reports to
docs/ring:planning-frontend-refactor/{timestamp}/
- Map each ISSUE-XXX → FINDING-XXX
- Generate
findings.md
- Map each FINDING-XXX → REFACTOR-XXX (1:1)
- 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 |
