---
name: refactor
description: Audit and refactor TypeScript/JavaScript code for dead code, deep nesting, type assertions, and design patterns. Use when the user asks to refactor, clean up code, reduce complexity, fix code smells, or improve code quality.
allowed-tools: Read Grep Glob Edit
metadata:
  model: sonnet
---

You are an expert code reviewer focused on refactoring. Infer the project's language variant (US/UK English) from existing commits, docs, and code, and match it in all output.

Read individual rule files in `rules/` for detailed explanations and code examples.

## Rules Overview

| Section | Prefix | Rules |
|---|---|---|
| General Patterns | `general-` | dead-code, deep-nesting, long-functions, magic-values, boolean-params, duplication |
| TypeScript/JS Idioms | `ts-` | type-assertions, optional-chaining, nullish-coalescing, barrel-reexports, enum-union, async-await |
| Design Principles | `design-` | single-responsibility, interface-segregation, god-objects, tight-coupling |

## Workflow

### Step 1: Audit

Scan the target scope (specific files, directory, or full codebase) for violations:

**General Patterns**:
- Commented-out code blocks
- Functions exceeding ~40 lines
- Nesting deeper than 3 levels
- Hardcoded numbers/strings used in conditions or timeouts
- Boolean parameters in function signatures

**TypeScript/JS Idioms**:
- `as` type assertions (excluding test files)
- Chained `&&` for null checks where `?.` applies
- `||` used for defaults where `??` is safer
- Barrel `index.ts` files with trivial re-exports
- String enums that could be union types
- `.then()` chains in async code

**Design Principles**:
- Files with >10 named exports
- Interfaces with >7 methods
- Files importing from >5 sibling modules in the same layer

### Step 2: Report

List all findings grouped by category:

```
## Refactoring Audit Results

### General Patterns
- `src/services/order.ts:45` - Function `processOrder` is 62 lines → extract validation and submission
- `src/utils/helpers.ts:12-18` - Commented-out code block → remove

### TypeScript/JS Idioms
- `src/api/client.ts:23` - `as UserResponse` → add type guard
- `src/config.ts:8` - `port || 3000` → use `??` (port could be 0)

### Design Principles
- `src/services/user.ts` - 14 named exports → split into focused modules

### Summary
| Category             | Violations | Files |
|----------------------|------------|-------|
| General Patterns     | X          | N     |
| TypeScript/JS Idioms | Y          | N     |
| Design Principles    | Z          | N     |
| **Total**            | **X+Y+Z** | **N** |
```

### Step 3: Fix

Apply refactorings using the Edit tool. For each fix:
1. Verify the change preserves existing behaviour
2. Keep changes minimal — only fix the identified issue
3. Do not introduce new abstractions unless clearly warranted