code-refiner

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?)