# Refactor

> Activate when improving code quality, reducing complexity, or aligning code with standards without changing behavior.

- Skill: `didacrios/refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add didacrios/refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/didacrios/refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: didacrios (https://skillmd.com/u/didacrios)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/didacrios/refactor

---


# Surgical Refactoring Protocol

A protocol for safely improving code quality without changing external behavior. Combines recursive tracing with incremental, test-verified transformations.

## When to Activate
- Cleaning up code after a feature is complete
- Reducing method length or cyclomatic complexity
- Aligning existing code with stack standards
- Extracting reusable logic from large methods
- Renaming symbols to match domain language

## Core Concepts
- **Behavior preservation** — refactoring must not change external behavior
- **Test shield** — green tests must exist before any refactoring begins
- **One method at a time** — incremental changes, verified after each step
- **The "Clean 20" rule** — methods over 20 lines are mandatory extraction targets

## Detailed Guidance

### Pre-Refactor Analysis
Before any modification, perform a recursive check:
- **Contracts:** Identify all interfaces or types the current code implements by peeking into project files.
- **Consumers:** Trace all methods that depend on this code to prevent breaking changes.
- **Test Shield:** Verify that a green test suite exists. If missing, the first "Baby Step" must be creating a test.

### Refactoring Targets (The "Clean 20" Rule)
Systematically apply these transformations:
- **Method Extraction:** If a method > 20 lines, extract logical sub-tasks into private helpers (10-20 lines).
- **Complexity Flattening:** Replace nested logic with early returns or collection pipelines (map/filter).
- **Naming Alignment:** Rename symbols to match the domain language found in the relevant stack skill.
- **Type Strengthening:** Replace `mixed`, `any`, or loose types with strict types or Value Objects.

### Execution Protocol
1. **The "Shadow" Step:** Propose the new architecture in a `<thought>` block. Explain how it aligns with the `recursive-exploration` skill.
2. **Incremental Apply:** Refactor only ONE method at a time.
3. **Verify:** Run tests after every single extraction to ensure the behavioral contract is intact.

### Output Format
For each refactor step:
- **Rationale:** Why? (e.g., "Flattened nested IFs to improve readability").
- **The Change:** Provide the specific refactored code block.
- **Recursive Next Step:** Identify the next target for refactoring within the file.

## Examples

**Input:** A 35-line method with nested conditionals.

**Step 1 output:**
- **Rationale:** "Method exceeds 20 lines. Extracting validation logic into `validateInput()`."
- **Change:** Show extracted method and updated caller.
- **Next:** "The remaining method is 18 lines. Next target: flatten the nested if/else at line 12."

## Guidelines
1. Never refactor without a green test suite — create tests first if missing
2. Trace all consumers before modifying any method signature
3. One method per step — never batch refactor
4. Run tests after every extraction
5. Methods must be 10-20 lines after refactoring
6. Replace loose types with strict types or Value Objects
7. Document rationale for every change

## Integration
- Depends on: `recursive-exploration` (tracing methodology), `typescript-standard` or `php-standard` (target standards)
- Related: `code-review` (refactor suggestions from reviews)

## Skill Metadata
- Created: 2025-06-01
- Last Updated: 2025-07-01
- Author: didacrios
- Version: 1.0.0