# Refactor > Refactor existing code for quality, performance, or maintainability. Enforces six quality principles with ratchet gate. - Skill: `cwijayasundara/refactor-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add cwijayasundara/refactor-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/cwijayasundara/refactor-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cwijayasundara (https://skillmd.com/u/cwijayasundara) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cwijayasundara/refactor-3 --- # Refactor Skill — Quality-Driven Code Improvement ## Usage ``` /refactor src/service/extraction.py /refactor src/repository/ ``` Provide a file path or directory. The skill analyzes the target against six quality principles, plans the changes, and executes them one principle at a time. --- ## Overview Refactoring improves the internal structure of existing code without changing its observable behavior. No new features. No behavior changes. Every change must trace to a violation of one of the six quality principles. --- ## Steps ### Step 1 — Read Quality Principles Read `.claude/skills/code-gen/SKILL.md` in full. The six principles are the refactoring standard. Every change planned in Step 4 must cite a specific principle. ### Step 2 — Analyze Current State For each file in the target path: - **Architecture compliance:** does the file import from a layer above it? (see layering rules in `architecture/SKILL.md`) - **Function lengths:** count lines in each function. Flag any over 50 lines. - **Type coverage:** identify any `any` (TypeScript) or missing type hints (Python). Count unannotated parameters and return types. - **Test coverage baseline:** run the test suite and record current pass/fail counts and coverage percentage. - **Dead code:** identify unused imports, unreachable branches, commented-out code. - **Documentation style:** identify comments that restate the code rather than explaining non-obvious decisions. Record findings in a structured list before proceeding. ### Step 3 — Identify Violations Map each finding from Step 2 to one of the six principles: 1. Small Modules — file exceeds 300 lines (block) or 200 lines (warning). 2. Static Typing — `any`, missing annotations, untyped domain concepts. 3. Functions Under 50 Lines — function body exceeds 50 lines. 4. Explicit Error Handling — bare `except`, untyped catches, swallowed errors. 5. No Dead Code — unused imports, commented-out code, unreachable branches. 6. Self-Documenting — comments that restate what the code does, not why. Only violations of these six principles justify a change. Do not refactor code that complies with all six principles. ### Step 4 — Plan Changes Produce a written plan before touching any code: ``` File: src/service/extraction.py Change: Split extract_data() into extract_raw(), validate_schema(), transform_fields() Principle: #3 — extract_data() is 87 lines Risk: One caller in api/routes.py — update import after split File: src/service/extraction.py Change: Add return type annotation to all 4 functions Principle: #2 — return types missing Risk: None ``` List every file, what will change, which principle it violates, and any known call-site impact. ### Step 5 — Execute One Principle at a Time Apply changes for one principle across all affected files. Then run the test suite. Then proceed to the next principle. Order of execution: 1. Static typing (lowest risk, foundation for other changes) 2. Dead code removal 3. Function decomposition 4. Module splitting (if needed) 5. Error handling 6. Self-documenting cleanup After each principle: run tests, run lint, run type checks. If anything breaks, fix it before moving to the next principle. ### Step 6 — Spawn code-reviewer After all changes are complete, spawn the `code-reviewer` agent on the full diff. The reviewer will return findings at three severity levels: - **BLOCK** — must fix before this refactor is considered complete. - **WARN** — should fix; document if deferring. - **INFO** — optional improvement. ### Step 7 — Fix BLOCK Findings Address every BLOCK finding. Re-run the reviewer after each fix cycle. Maximum 3 retry cycles. If BLOCK findings remain after 3 cycles, stop and report the unresolved issues. Do not ship code with unresolved BLOCK findings. --- ## Non-Negotiable Rules - **Tests must pass after every change.** If a refactor breaks a test, fix the code — not the test. - **No behavior changes.** The refactored code must produce identical outputs for all existing inputs. - **No new features.** If you identify a missing capability, open a story and use `/improve`. - **Every change traces to a principle.** If you cannot cite which of the six principles a change addresses, do not make the change. - **Update all call sites.** When renaming or moving a symbol, update every import and reference before committing. --- ## Output The target path contains refactored code that: - Passes the full test suite. - Has no new lint or type errors. - Has no BLOCK findings from the code reviewer. - Has coverage equal to or better than the baseline recorded in Step 2. --- ## Gotchas - **Refactoring without tests.** If the target code has no tests, write characterization tests before refactoring. Refactoring untested code silently introduces regressions. - **Big-bang changes.** Applying all principles at once makes failures hard to diagnose. Execute one principle at a time. - **Renaming without updating imports.** A renamed function that is still referenced by its old name will fail at runtime, not compile time in Python. Search all call sites. - **Breaking layering while splitting modules.** When extracting a new file, verify it does not introduce an upward dependency. - **Deleting "unused" code that is used dynamically.** Python's `getattr`, decorator registries, and plugin systems reference symbols by string. Verify with a project-wide search before deleting.