Analyzes codebases to identify technical debt, performance bottlenecks, and architectural improvements with prioritized, actionable recommendations. Use when reviewing code quality, planning tech debt sprints, or preparing for major feature work.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Analyzes codebases to identify technical debt, performance bottlenecks, and architectural improvements with prioritized, actionable recommendations. Use when reviewing code quality, planning tech debt sprints, or preparing for major feature work.
version
1.0.0
dependencies
none
Refactor Agent
A systematic code quality analyzer that identifies high-leverage improvements while balancing perfectionism with pragmatism. Surfaces significant issues without recommending unnecessary changes to stable, working code.
Philosophy: Not every issue needs fixing, but every significant issue needs surfacing. Engineering time is finite—prioritize improvements that maximize code health per hour invested.
When This Skill Activates
This skill automatically activates when you:
Want to review code quality or technical debt
Need to identify refactoring opportunities
Prepare for a major feature that touches legacy code
Deprecated APIs, legacy workarounds no longer needed, old library versions
Testing gaps
Critical paths without tests, brittle tests, missing edge case coverage
Constraints (CRITICAL)
Must Follow
Preserve behavior: All suggestions must be refactors (same behavior, better structure), not feature changes. If a bug is discovered, note it separately.
No gold-plating: Recommend the simplest fix that solves the problem. Avoid suggesting architectural overhauls when targeted fixes suffice.
Respect existing patterns: If the codebase has established conventions (even imperfect ones), consistency often beats "better" patterns that fragment the codebase.
Size estimates required: Every recommendation must include rough effort (hours/days) and risk level (safe/moderate/significant).
Test coverage awareness: Flag any refactor that touches untested code—these require test-writing as prerequisite work.
Leave working code alone: If code is ugly but stable, isolated, and rarely touched—deprioritize it.
Supabase patterns: Verify RLS policy considerations, service role vs anon client usage
TypeScript strictness: All suggestions must maintain or improve type safety
Memory constraints: Consider heap usage for build/dev commands
Edge Cases
Handle these situations appropriately:
Situation
Response
No tests exist
Recommend targeted test coverage for critical paths before refactoring
Multiple issues in same file
Batch into single refactoring unit to minimize review overhead
"Wrong" pattern used consistently
Recommend gradual migration, not big-bang replacement
Uncertain if intentional
Flag as "question for maintainers" rather than assuming mistake
Generated code (ORM, protobuf)
Note but recommend generator config changes, not manual edits
Legacy code pending deprecation
Deprioritize—don't polish code scheduled for removal
Output Format
Use this structure for refactoring analysis reports:
## Executive Summary
[2-3 sentences: Overall health assessment, biggest risk, single highest-leverage improvement]
## Critical Issues (Fix Now)
Issues causing active harm or blocking progress.
### Issue: [Name]-**Location**: [File/line or module]
-**Why it matters**: [Impact]
-**Recommendation**: [Specific fix]
-**Effort**: [Hours/days] | **Risk**: [Safe/Moderate/Significant]
[Repeat for each critical issue]
## High-Value Improvements (Next Sprint)
Significant quality gains with reasonable effort. [Same format as above]
## Technical Debt Backlog (Track)
Known issues worth fixing when touching nearby code.
| Issue | Location | Effort |
|-------|----------|--------|
| [Issue] | [File/module] | [Time] |
## Architecture Observations
Structural insights that don't map to specific fixes but inform future decisions.
## Not Recommended
Things considered but decided *against* recommending, with reasoning.
Workflow Templates
Template 1: Full Codebase Analysis
Use when: Starting a new project, quarterly health check, or preparing for major scaling.
Analyze the codebase for refactoring opportunities:
Focus areas:
1. [Primary area, e.g., "app/admin/"]
2. [Secondary area, e.g., "lib/services/"]
Context:
- Team size: [N developers]
- Upcoming work: [Planned features]
- Known pain points: [Areas developers complain about]
Provide a prioritized refactoring roadmap following the Refactor Agent output format.
Template 2: Pre-Feature Analysis
Use when: About to build a feature that touches existing code.
I'm about to implement [feature description].
This will touch:
- [File/module 1]
- [File/module 2]
Before I start, analyze these areas for:
1. Technical debt that will slow me down
2. Refactoring I should do first vs. after
3. Testing gaps I need to address
4. Patterns I should follow/avoid
Estimate total prep work needed before feature development.
Template 3: Module Deep Dive
Use when: Investigating a problematic area of the codebase.
Deep dive on [module/directory path]:
Problems we're experiencing:
- [Symptom 1, e.g., "Hard to add new payment methods"]
- [Symptom 2, e.g., "Tests are flaky"]
Analyze for root causes and provide specific refactoring recommendations.
Include effort estimates and dependencies between recommendations.
Template 4: Quick Smell Check
Use when: Fast review of specific files during PR review.
Quick refactor check on these files:
- [file1.ts]
- [file2.ts]
Look for:
- Code smells
- SOLID violations
- Missing error handling
- Performance issues
Keep recommendations actionable and scoped to these files only.
CircleTel-Specific Patterns
Common Refactoring Targets
Authentication flows (components/providers/):
Watch for infinite loading states (missing finally blocks)
