| name | Refactor Agent |
| description | 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
- Plan a tech debt sprint or cleanup cycle
- Analyze a module before significant changes
- Review code for architectural improvements
- Assess codebase health before scaling/team growth
Keywords: refactor, technical debt, code smell, code quality, cleanup, improve code, review architecture, code review, anti-pattern, complexity, coupling, dead code, duplication
Core Approach
1. Structural Scan
Map architecture first—identify modules, dependencies, and boundaries before diving into line-level issues.
Look for:
- Circular dependencies between modules
- God classes/files (doing too much)
- Unclear ownership boundaries
- Missing abstraction layers
- Leaky abstractions
2. Pattern Recognition
Detect recurring anti-patterns and code smells. Distinguish between:
- "Ugly but stable" code → Lower priority
- "Clean but fragile" code → Higher priority
3. Impact Assessment
For each issue, evaluate:
| Factor | Question |
|---|
| Blast radius | How much breaks if this fails? |
| Touch frequency | How often do developers modify this? |
| Fix effort | Hours or days to address? |
Prioritization formula: High-impact + High-touch + Low-effort = Fix first
4. Dependency Analysis
Trace coupling between components:
- Load-bearing code: Everything depends on it → Requires more care
- Isolated modules: Self-contained → Safer to refactor
5. Future-Proofing Check
Consider how current structure handles likely changes:
- New features in the roadmap
- Scaling requirements
- Team growth
Flag areas where current design forces rewrites within 6-12 months.
Analysis Categories
Evaluate each category when analyzing code:
| Category | What to Look For |
|---|
| Duplication | Copy-paste code, near-duplicate functions, repeated patterns that should be abstracted |
| Complexity | High cyclomatic complexity, deep nesting, long functions (>50 lines), files doing too much |
| Coupling | Tight coupling between modules, circular dependencies, feature envy, inappropriate intimacy |
| Naming | Misleading names, inconsistent conventions, abbreviations that obscure meaning |
| Error handling | Swallowed exceptions, inconsistent error patterns, missing edge case handling |
| Performance | N+1 queries, unnecessary computation in loops, missing caching opportunities, memory leaks |
| Security | Hardcoded secrets, SQL injection vectors, unvalidated inputs, exposed internals |
| Dead code | Unused functions, unreachable branches, commented-out code, orphaned files |
| Outdated patterns | 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.
CircleTel-Specific Constraints
- Next.js 15 patterns: Ensure suggestions follow async params, server/client component separation
- 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)
- Check auth context provider exclusions
- Verify three-context system boundaries
API routes (app/api/):
- Next.js 15 async params pattern
- Service role vs authenticated client usage
- Consistent error response format
Coverage system (lib/coverage/):
- 4-layer fallback complexity
- MTN API anti-bot headers
- Caching strategy consistency
Payment flows (lib/payment/, components/checkout/):
- NetCash webhook verification
- State machine transitions
- Error recovery paths
Files That Are Load-Bearing
High-impact, requires extra care:
lib/supabase/server.ts - All server-side DB accesscomponents/providers/CustomerAuthProvider.tsx - Customer auth statelib/coverage/aggregation-service.ts - Coverage decision logicapp/api/webhooks/ - Payment and integration webhooks
Known Technical Debt Areas
Reference when prioritizing:
- B2B KYC workflow (64% complete, active development)
- Customer dashboard tables (spec ready, not implemented)
- ZOHO sync (Supabase-first pattern, async sync)
Validation Checklist
After completing a refactoring analysis:
Best Practices
- Start structural, then tactical: Map the forest before examining trees
- ROI over perfection: Best fix is simplest one that solves the problem
- Batch related changes: Multiple issues in one module = one PR
- Test before touching: No tests = write tests first, then refactor
- Consistency over novelty: Match existing patterns unless they're actively harmful
- Document trade-offs: Explain why you recommend X over Y
- Scope creep awareness: Refactor scope expands easily—set boundaries early
Risk Levels Explained
| Level | Definition | Approach |
|---|
| Safe | Isolated change, well-tested area, low blast radius | Can merge with standard review |
| Moderate | Touches multiple files, some test coverage, medium blast radius | Extra review, staged rollout |
| Significant | Load-bearing code, gaps in tests, high blast radius | Dedicated testing cycle, feature flag, gradual migration |
Related Skills
- bug-fixing: When analysis reveals bugs rather than refactoring needs
- database-migration: When refactoring requires schema changes
- context-manager: For large codebase analysis to manage token budget
Version: 1.0.0
Last Updated: 2025-12-15
Maintained By: CircleTel Development Team
Based On: Principal engineer code quality review methodology
