/code-refiner

name: code-refiner
description: 'Deep code simplification and refactoring preserving behavior across Python, Go, TypeScript, Rust. Targets complexity, anti-patterns, readability debt. Triggers on: "simplify this code", "refactor for clarity", "reduce complexity", "make this more readable", "tech debt cleanup", "too much nesting". NOT for deepening shallow modules or redesigning a module''s interface or seam, use module-deepening.'
metadata:
  version: 1.1.2
  category: review
  tags: [refactoring, code-quality, simplification, readability]
  difficulty: intermediate
  phase: review

Code Refiner

A structured, multi-pass code refinement skill that transforms complex, verbose, or tangled code into clean, idiomatic, maintainable implementations — without changing what the code does.

Philosophy

The goal is **not** fewer lines. The goal is code that a tired engineer at 2am can read, understand, and safely modify. Every change must pass three tests:

1. **Behavioral equivalence** — identical inputs produce identical outputs, side effects, and errors 2. **Cognitive load reduction** — a reader unfamiliar with the code understands it faster after the change 3. **Maintenance leverage** — the change makes future modifications easier, not harder

When clarity and brevity conflict, clarity wins. When idiom and explicitness conflict, consider the team's experience level. When DRY and locality conflict, prefer locality for code read more than modified.

Prerequisites

• **git** — used in Phase 1 for scope detection (`git diff`) when the user doesn't specify target files
• **Python 3.10+** — required to run `scripts/complexity_report.py` for quantitative complexity metrics

Workflow

Follow this sequence. Each phase builds on the previous one. Do not skip phases, but adapt depth to the scope of the request (a single function gets a lighter pass than a full module).

Phase 1: Reconnaissance

Before touching anything, build a mental model:

1. **Identify scope** — What files/functions are in play? If the user hasn't specified, check recent git modifications: `git diff --name-only HEAD~5` or `git diff --staged --name-only` 2. **Detect language and ecosystem** — Read file extensions, imports, config files (package.json, pyproject.toml, go.mod, Cargo.toml). Load the appropriate language reference from `references/` if needed for idiom-specific guidance 3. **Read project conventions** — Check for CLAUDE.md, .editorconfig, linter configs (eslint, ruff, golangci-lint, clippy). These override generic idiom preferences 4. **Understand test coverage** — Locate test files. If tests exist, note the test runner so you can verify behavioral equivalence after changes 5. **Baseline complexity snapshot** — For each target function/method, mentally note:

• Nesting depth (max indentation levels)
• Number of branches (if/else/match/switch arms)
• Number of early returns vs single-exit
• Parameter count
• Lines of code
• Number of responsibilities (does it do more than one thing?)

Phase 2: Structural Analysis

Identify what's actually wrong before reaching for solutions. Categorize issues by severity:

**Critical** (always fix):

• Dead code (unreachable branches, unused variables/imports)
• Redundant operations (double-checking the same condition, re-computing cached values)
• Logic that can be replaced by a stdlib/language built-in
• Mutation of shared state that could be avoided

**High** (fix unless there's a clear reason not to):

• Functions with >3 levels of nesting
• Functions with >5 parameters
• God functions (>40 lines or >3 responsibilities)
• Repeated code blocks (3+ occurrences of similar logic)
• Inverted or confusing boolean logic
• Stringly-typed enumerations

**Medium** (fix when it improves clarity without adding risk):

• Unclear variable/function names
• Missing or misleading type annotations
• Unnecessary intermediate variables
• Over-abstraction (wrappers that add no value)
• Comments that restate the code instead of explaining _why_

**Low** (fix only in a dedicated cleanup pass):

• Inconsistent formatting (defer to linter)
• Import ordering
• Trailing whitespace, line length

Phase 3: Refactoring Execution

Apply changes using these tactics, ordered by impact-to-risk ratio:

3a. Eliminate Dead Weight

Remove before restructuring. Less code = less to think about.

• Delete unused imports, variables, functions
• Remove unreachable branches (but verify they're truly unreachable)
• Strip comments that restate the obvious (keep comments that explain _why_)
• Remove no-op wrapper functions that just forward calls

3b. Flatten Structure

Reduce nesting and cognitive load:

• **Guard clauses**: Convert deep `if` nesting to early returns
• **Extract conditions**: Name complex boolean expressions (`is_valid_order = ...`)
• **Decompose loops**: If a loop does filter + transform + accumulate, break it apart

(or use language-appropriate constructs: list comprehensions, iterators, streams)

• **Invert conditionals**: When the `else` branch is the "happy path", flip it

3c. Consolidate and Name

Make the code's intent visible:

• **Extract functions** for repeated logic or distinct responsibilities
• Name by _what it accomplishes_, not _how it works_
• Functions should do one thing at one level of abstraction
• **Replace magic values** with named constants
• **Rename for intent**: `data` → `user_records`, `process` → `validate_and_enqueue`
• **Group related parameters** into a config/options struct when count > 3

3d. Leverage Language Idioms

Apply language-specific patterns (consult `references/<language>.md` for details):

• Python: comprehensions, context managers, dataclasses, structural pattern matching
• Go: table-driven tests, error wrapping, functional options, interface satisfaction
• TypeScript: discriminated unions, branded types, const assertions, satisfies
• Rust: iterator chains, `?` operator, From/Into, new