tomevault-io Refactor Skill
Mission
Provide unified, systematic code refactoring through comprehensive validation, ensuring safe improvements while preserving functionality.
What this skill accomplishes:
- Cleans up code while maintaining functionality
- Improves structure and maintainability
- Optimizes performance with measured improvements
- Enhances security through vulnerability scanning
- Strengthens type safety in TypeScript codebases
Scope Definition
This skill applies to:
- Code cleanup and simplification
- Structure improvement and reorganization
- Performance optimization with metrics
- Security vulnerability remediation
- Type safety enhancement
- Duplication elimination
Related Skills
For tasks outside this scope, consider:
/studio build- New feature implementation/studio review- Code review without refactoring- Edit tool - Simple renames or documentation updates
/studio build --test- Test writing
Tool Selection Standards
| Task | Recommended Tool | Avoid |
|---|---|---|
| Find code by meaning | grepai search |
grep/egrep/find |
| Read file contents | Read tool |
cat/head/tail |
| List files | Glob tool |
ls/dir/find |
| Search file contents | Grep tool |
grep/rg |
Decision Guide:
- Need to search? →
grepai searchor/toolkit search - Need to read? →
Read tool - Need to list? →
Glob tool - Need to grep? →
Grep tool
Execution Protocol
Step 1: Analysis (Always First)
Understand before acting:
- Use semantic search to locate relevant code
- Read files with the Read tool
- Identify complexity hotspots
- Detect duplication patterns
- Assess test coverage
Step 2: Planning (For Multi-File Changes)
Create a plan when:
- Modifying 3+ files
- Restructuring a module
- Running subagents
- Using analyze/full/resolve modes
Step 3: Execution (Incremental)
Apply changes safely:
- Make small, verifiable changes
- Run tests after each change
- Commit logical units
- Document rationale
Step 4: Verification
Confirm success:
- All tests passing
- No type errors
- Metrics documented
- No regressions detected
Quality Gates
Pre-Refactor Checklist
Analysis Complete:
- [ ] Semantic search performed
- [ ] Relevant files read
- [ ] Complexity assessed
- [ ] Test coverage verified
Post-Refactor Checklist
Validation Complete:
- [ ] All tests passing
- [ ] No type errors
- [ ] No regressions
- [ ] Metrics improved
- [ ] Documentation updated
Mode-Specific Gates
| Mode | Additional Gates |
|---|---|
--profile |
Performance improved >= 20% |
--security |
All P0/P1 vulnerabilities fixed |
--types |
Zero any, coverage >= 95% |
--clean |
Net code reduction achieved |
Success Metrics
Universal Metrics
- Test Status: All tests passing
- Type Safety: No type errors
- Complexity: Reduced from baseline
- Coverage: Increased from baseline
- Regressions: Zero detected
- Documentation: Complete and accurate
Mode-Specific Metrics
| Mode | Key Metrics |
|---|---|
--profile |
Execution time, memory usage, query count |
--security |
P0/P1 vulnerabilities fixed |
--types |
Type coverage %, any count |
--clean |
Lines removed, duplication eliminated |
Mode Quick Reference
| Mode | Purpose | When to Use |
|---|---|---|
--quick |
Auto-fix low-risk items | Risk < 30, complexity < 8 |
--full |
Complete workflow (default) | Standard refactoring |
--analyze |
Analysis only | Detect and catalog issues |
--review |
Create action plan | Prioritize by severity |
--resolve |
Apply validated changes | From review results |
--verify |
Comprehensive verification | Validate results |
--profile |
Performance optimization | Slow functions, high memory |
--security |
Security scan | OWASP compliance, audit |
--types |
TypeScript improvement | Poor types, any usage |
Scope Options
| Option | Purpose | Example |
|---|---|---|
--scope=recent |
Recent changes only (default) | /studio refactor --quick |
--scope=file:PATH |
Specific file | --scope=file:src/auth/jwt.ts |
--scope=directory:PATH |
Entire directory | --scope=directory:src/features/auth |
--scope=all |
Entire codebase | --scope=all |
--scope=bug |
Bug fixing | --scope=bug "TypeError in auth" |
Auto-Team System
Agent teams activate automatically for complex refactors:
| Criterion | Threshold | Team Size |
|---|---|---|
| Files to analyze | >= 5 | 2 agents |
| Modes | analyze/full/profile/security/types | 2-3 agents |
| Complexity detected | High | 2-3 agents |
Disable teams: Add --no-team flag
Examples
# Quick refactor
/studio refactor --quick
# Full workflow with performance profiling
/studio refactor --full --profile
# Security audit
/studio refactor --security --scope=all
# Type safety improvement
/studio refactor --types --scope=directory:src/features
# Bug-specific refactor
/studio refactor --scope=bug "TypeError in auth"
# Team-based performance + security
/studio refactor --profile --security --team
See Also
Full documentation: @REFERENCE.md
- Mode details (workflow, examples, success criteria)
- Specialized modes (profile, security, types)
- Subagent collaboration
- Common patterns (Extract Method, etc.)
- Configuration
- Integration
Refactor Skill v2.1.0
Converted and distributed by TomeVault — claim your Tome and manage your conversions.