refactor

Refactor Skill

Goal

Restructure existing code to improve quality, readability, or maintainability without changing external behavior. Every refactor must be provably safe through tests and type checks.

Activation Triggers

• User says "refactor", "restructure", "clean up", "reorganize", or "simplify"
• Code review identified structural issues
• Technical debt needs to be addressed
• Code duplication needs to be consolidated

Safety Checklist (Pre-Flight)

Before making any changes, verify all of these:

1. Git State is Clean

# Ensure no uncommitted changes
git status --short 2>/dev/null

If there are uncommitted changes, ask the user to commit or stash them first. Refactoring on a dirty working tree makes rollback difficult.

2. Tests Exist and Pass

# Run full test suite
npm test 2>&1 | tail -30

# Check exit code
echo "Exit code: $?"

If no tests exist: Stop and suggest using the test-generation skill first. Refactoring without tests is risky - you cannot verify behavior is preserved.

3. Types Check Clean

# Verify no type errors
npm run typecheck 2>&1 | tail -20 || tsc --noEmit 2>&1 | tail -20

Process

1. Define Scope

Clearly identify what is being refactored and why:

Questions to answer:

• What specific code needs restructuring?
• Why does it need to change? (readability, performance, maintainability)
• What is explicitly NOT being changed?
• What is the expected outcome?

# Understand the code to refactor
cat [target-file] | head -100

# Find all usages/callers
grep -rn "functionOrClassName" src/ --include="*.ts" --include="*.js" | head -20

# Check test coverage for this code
find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | xargs grep -l "functionOrClassName" 2>/dev/null

2. Verify Tests Pass (Before)

# Run tests - record baseline
npm test 2>&1 | tail -30

# Run typecheck - record baseline
npm run typecheck 2>&1 | tail -20 || tsc --noEmit 2>&1 | tail -20