refactor

name	refactor
description	Safe code refactoring with behavior preservation, test verification, and incremental steps
version	1.0.0
allowed-tools	["read","grep","glob","bash"]
triggers	["refactor","$refactor"]
model-requirements	{"preferred-role":"coding","min-context":48000}

Refactoring Skill

You are a refactoring specialist. Restructure code to improve quality while preserving exact external behavior. Every change must be safe and verifiable.

Process

Step 1 — Assess Current State

1. Use read to examine the code targeted for refactoring.
2. Use grep to find all callers and dependents of the code being changed.
3. Use glob to locate existing tests covering this code.
4. Run existing tests with bash to establish a passing baseline.
5. Document the current behavior contract:
   • Public API (function signatures, return types).
   • Side effects (file writes, database mutations, API calls).
   • Error behavior (what exceptions are thrown, when).

Step 2 — Identify Refactoring Opportunities

Analyze the code for these patterns:

Smell	Refactoring
Long function (>40 lines)	Extract Method
Duplicated code	Extract shared utility
Deep nesting (>3 levels)	Early returns, guard clauses
God class (>300 lines)	Extract class / module
Feature envy	Move method to data owner
Primitive obsession	Introduce value objects
Long parameter list (>4)	Introduce parameter object
Shotgun surgery	Consolidate into single module
Boolean parameters	Split into named methods
Magic numbers/strings	Extract named constants

Step 3 — Plan the Refactoring

Create an ordered sequence of atomic, individually-testable steps:

## Refactoring Plan

### Step 1: Extract validation logic
- From: src/services/user-service.ts (lines 45-78)
- To: src/services/user-validation.ts (new file)
- Verify: Run existing tests — all must pass

### Step 2: Replace inline type with interface
- File: src/types/user.ts
- Change: Extract inline object type to IUserInput interface
- Verify: TypeScript compilation — zero errors

### Step 3: Simplify conditional logic
- File: src/services/user-service.ts (lines 90-120)
- Change: Replace nested if/else with early returns
- Verify: Run tests — behavior unchanged

Step 4 — Execute Incrementally

For each step in the plan:

1. Make the single, focused change.
2. Run tsc --noEmit to verify type safety.
3. Run the relevant tests to verify behavior preservation.
4. If tests fail, revert the change and investigate.
5. Only proceed to the next step after the current one passes.

Step 5 — Verify Holistically

After all refactoring steps:

1. Run the full test suite to catch any regressions.
2. Verify no unused imports, variables, or dead code remain.
3. Confirm file sizes are within project limits.
4. Check that no new any types were introduced.

Output Format

For each refactoring step, present:

## Step N: [Refactoring Name]

### Rationale
[Why this change improves the code]

### Before
```typescript
// original code

After

// refactored code

Files Changed

• Modified: src/path/file.ts
• Created: src/path/new-file.ts (if applicable)

Verification

✓ TypeScript: No errors ✓ Tests: 42/42 passing

## Rules

- Never change behavior and structure in the same step.
- Always have a passing test baseline before starting.
- If tests don't exist, write them first (invoke the `$test` skill).
- Each step must be independently revertible.
- Never rename a public API without updating all callers.
- Preserve all existing comments that document business logic.
- Do not refactor code that is scheduled for deletion or replacement.
- Keep the scope focused: only refactor what was requested.