refactor-ops

What this skill does

# Refactor Operations

Comprehensive refactoring skill covering safe transformation patterns, code smell detection, dead code elimination, and test-driven refactoring methodology.

## Refactoring Decision Tree

```
What kind of refactoring do you need?
│
├─ Extracting code into a new unit
│  ├─ A block of statements with a clear purpose
│  │  └─ Extract Function/Method
│  │     Identify inputs (params) and outputs (return value)
│  │
│  ├─ A UI element with its own state or props
│  │  └─ Extract Component (React, Vue, Svelte)
│  │     Move JSX/template + related state into new file
│  │
│  ├─ Reusable stateful logic (not UI)
│  │  └─ Extract Hook / Composable
│  │     React: useCustomHook, Vue: useComposable
│  │
│  ├─ A file has grown beyond 300-500 lines
│  │  └─ Extract Module
│  │     Split by responsibility, create barrel exports
│  │     Watch for circular dependencies
│  │
│  ├─ A class does too many things (SRP violation)
│  │  └─ Extract Class / Service
│  │     One responsibility per class, use dependency injection
│  │
│  └─ Magic numbers, hardcoded strings, env-specific values
│     └─ Extract Configuration
│        Constants file, env vars, feature flags
│
├─ Renaming for clarity
│  ├─ Variable, function, or method
│  │  └─ Rename Symbol
│  │     Update all references (IDE rename or ast-grep)
│  │
│  ├─ File or directory
│  │  └─ Rename File + Update Imports
│  │     git mv to preserve history, update all import paths
│  │
│  └─ Module or package
│     └─ Rename Module + Update All Consumers
│        Search for all import/require references
│        Consider re-exporting from old name temporarily
│
├─ Moving code to a better location
│  ├─ Function/class to a different file
│  │  └─ Move + Re-export from Original
│  │     Leave re-export for one release cycle
│  │
│  ├─ Files to a different directory
│  │  └─ Restructure + Update All Paths
│  │     Use IDE refactoring or find-and-replace
│  │
│  └─ Reorganize entire directory structure
│     └─ Incremental Migration
│        Move one module at a time, keep tests green
│
├─ Simplifying existing code
│  ├─ Function is too simple to justify its own name
│  │  └─ Inline Function
│  │     Replace call sites with the body
│  │
│  ├─ Variable used only once, right after assignment
│  │  └─ Inline Variable
│  │     Replace variable with expression
│  │
│  ├─ Deep nesting (> 3 levels)
│  │  └─ Guard Clauses + Early Returns
│  │     Invert conditions, return early
│  │
│  └─ Complex conditionals
│     └─ Decompose Conditional
│        Extract each branch into named function
│
└─ Removing dead code
   ├─ Unused imports
   │  └─ Lint + Auto-fix (eslint, ruff, goimports)
   │
   ├─ Unreachable code branches
   │  └─ Static analysis + manual review
   │
   ├─ Orphaned files (no imports point to them)
   │  └─ Dependency graph analysis (knip, ts-prune, vulture)
   │
   └─ Unused exports
      └─ ts-prune, knip, or manual grep for import references
```

## Safety Checklist

Run through this checklist before starting any refactoring:

```
Pre-Refactoring
[ ] All tests pass (full suite, not just related tests)
[ ] Working tree is clean (git status shows no uncommitted changes)
[ ] On a dedicated branch (not main/master)
[ ] CI is green on the base branch
[ ] You understand what the code does (read it, don't assume)
[ ] Characterization tests exist for untested code you will change

During Refactoring
[ ] Each commit compiles and all tests pass
[ ] Commits are small and focused (one refactoring per commit)
[ ] No behavior changes mixed with structural changes
[ ] Running tests after every change (use --watch mode)

Post-Refactoring
[ ] Full test suite passes
[ ] No new warnings from linter or type checker
[ ] Code review requested (refactoring PRs need fresh eyes)
[ ] Performance benchmarks unchanged (if applicable)
[ ] Documentation updated (if public API changed)
```

## Extract Patterns Quick Reference

| Pattern | When to Use | Key Considerations |
|---------|-------------|-------------------|
| **Extract Function** | Block of code has a clear single purpose, used or could be reused | Name should describe WHAT, not HOW. Pure functions preferred. |
| **Extract Component** | UI element has own state, props, or rendering logic | Props interface should be minimal. Avoid prop drilling. |
| **Extract Hook/Composable** | Stateful logic shared across components | Must start with `use`. Return stable references. |
| **Extract Module** | File exceeds 300-500 lines, has multiple responsibilities | One module = one responsibility. Barrel exports for public API. |
| **Extract Class/Service** | Object handles too many concerns | Dependency injection over hard-coded dependencies. |
| **Extract Configuration** | Magic numbers, environment-specific values, feature flags | Type-safe config objects over loose constants. |

## Rename Patterns Quick Reference

| What to Rename | Method | Pitfalls |
|----------------|--------|----------|
| **Variable/function** | IDE rename (F2) or `ast-grep` | String references (logs, error messages) not caught by IDE |
| **Class/type** | IDE rename + update file name to match | Serialized data may reference old name (JSON, DB) |
| **File** | `git mv old new` + update all imports | Import paths in test files, storybook, config files often missed |
| **Directory** | `git mv` + bulk import update | Barrel re-exports, path aliases in tsconfig/webpack |
| **Package/module** | Rename + re-export from old name | External consumers need deprecation period |

## Move/Restructure Quick Reference

| Scenario | Strategy | Safety Net |
|----------|----------|------------|
| **Single file move** | `git mv` + update imports + re-export from old path | `rg 'old/path'` to find all references |
| **Multiple related files** | Move together, update barrel exports | Run type checker after each move |
| **Directory restructure** | Incremental: one directory per PR | Keep old paths working via re-exports |
| **Monorepo package split** | Extract to new package, update all consumers | Version the new package, pin consumers |

## Dead Code Detection Workflow

```
Step 1: Automated Detection
│
├─ TypeScript/JavaScript
│  ├─ knip (comprehensive: files, deps, exports)
│  │  └─ npx knip --reporter compact
│  ├─ ts-prune (unused exports)
│  │  └─ npx ts-prune
│  └─ eslint (unused vars/imports)
│     └─ eslint --rule 'no-unused-vars: error'
│
├─ Python
│  ├─ vulture (dead code finder)
│  │  └─ vulture src/ --min-confidence 80
│  ├─ ruff (unused imports)
│  │  └─ ruff check --select F401
│  └─ coverage.py (unreachable branches)
│     └─ coverage run && coverage report --show-missing
│
├─ Go
│  └─ staticcheck / golangci-lint
│     └─ golangci-lint run --enable unused,deadcode
│
├─ Rust
│  └─ Compiler warnings (dead_code, unused_imports)
│     └─ cargo build 2>&1 | rg 'warning.*unused'
│
Step 2: Manual Verification
│  ├─ Check if "unused" code is used via reflection/dynamic import
│  ├─ Check if exports are part of public API consumed externally
│  ├─ Check if code is used in scripts, tests, or tooling not in the scan
│  └─ Check if code is behind a feature flag or A/B test
│
Step 3: Remove with Confidence
│  ├─ Remove in small batches, not all at once
│  ├─ One commit per logical group of dead code
│  └─ Keep git history -- you can always recover
```

## Code Smell Detection

| Smell | Heuristic | Refactoring |
|-------|-----------|-------------|
| **Long function** | > 20 lines or > 5 levels of indentation | Extract Function, Decompose Conditional |
| **God object** | Class with > 10 methods or > 500 lines | Extract Class, Split by responsibility |
| **Feature envy** | Method uses another object's data more than its own | Move Method to the class whose data it uses |
| **Duplicate code** | Same logic in 2+ places (> 5 similar lines) | Extract Function, Extract Module |
| **Deep nesting** | > 3 levels of if/for/while nesting | Guard Clauses, Early Returns, Extract Function |
| **Primitive obsession** | Using strings/n