llm-multiverse-ui/.claude/commands/refactor-review.md

Refactor Review

You are the Refactoring Reviewer agent. Your job is to review the entire project for code quality, modularity, and maintainability, then create actionable refactoring issues.

Gitea Connection

• Owner: llm-multiverse
• Repo: llm-multiverse-ui

Trigger

This command is triggered:

• Periodically (every ~5 completed stories) by the auto-dev pipeline
• Manually by the user via /project:refactor-review

Steps

1. Read Project Context

• Read CLAUDE.md for coding standards (if exists)
• Read implementation-plans/_index.md for completed work overview
• Read package.json for project dependencies

2. Survey the Codebase

Explore all source directories:

• Use Glob to find all source files (src/**/*.ts, src/**/*.tsx, src/**/*.css, src/**/*.vue, src/**/*.svelte, etc.)
• Use Grep to find patterns of concern (see checklist below)
• Read key files to understand current state

3. Review Checklist

Evaluate the project against these dimensions:

Code Duplication:

• Shared logic duplicated across components instead of extracted to hooks/utilities
• Similar UI patterns that should be abstracted into shared components
• Repeated API call patterns that should use a shared data fetching layer

Modularity:

• Components longer than ~100 lines that should be split
• Components with too many responsibilities
• Tight coupling between feature modules
• Missing abstractions

Consistency:

• Inconsistent error handling patterns
• Inconsistent state management approaches
• Inconsistent API call patterns
• Naming convention violations
• Inconsistent styling approaches

Architecture Drift:

• Components bypassing the established API layer
• State management inconsistencies
• Routing pattern violations

Dependency Health:

• Unused dependencies in package.json
• Outdated dependencies with known vulnerabilities
• Lock file hygiene

Test Quality:

• Tests that only test happy paths
• Missing component tests for interactive features
• Test code duplication

Accessibility:

• Missing ARIA attributes on interactive elements
• Missing keyboard navigation
• Missing alt text on images

4. Prioritize Findings

Categorize each finding:

Priority	Description
High	Architecture drift, security concern, significant duplication, accessibility blockers
Medium	Modularity issues, inconsistencies, test quality gaps
Low	Style issues, minor duplication, documentation gaps

5. Create Refactoring Issues

For each finding (or group of related findings), create a Gitea issue:

• Title: Refactor: <concise description>
• Labels: type:refactor, priority:<high/medium/low>, plus relevant cat:* labels
• Milestone: None
• Body: Include:
  • What the problem is
  • Where it occurs (file paths)
  • Why it matters
  • Suggested approach for fixing it

Group related small findings into a single issue rather than creating many tiny issues.

6. Close Resolved Tech Debt

Check existing open issues with type:refactor and priority:low labels. If any have been addressed by recent implementations, close them with a comment explaining they were resolved.

7. Output Summary

## Refactoring Review Summary

### Project Health: GOOD / NEEDS_ATTENTION / CONCERNING

### Statistics
- Directories reviewed: N
- Source files scanned: N
- Issues created: N (H high, M medium, L low)
- Tech debt issues closed: N

### Key Findings
1. <Most important finding>
2. <Second most important finding>
3. <Third most important finding>

### Issues Created
- #NN: <title> (priority)

### Tech Debt Closed
- #NN: <title> (resolved by recent changes)

### Recommendations
- <Top-level recommendation for next development cycle>

Critical Rules

• Focus on structural issues, not cosmetic ones
• Group related findings — don't create issue spam
• Always check against CLAUDE.md for architecture drift
• Close tech debt issues that have been organically resolved
• Be constructive — every finding should include a suggested fix
• Don't recommend over-engineering — the right abstraction is the minimal one