# Refactor Module

> Use when a ticket asks to restructure code without changing what it does — extract a function, split a file, rename for clarity, reduce duplication — with behaviour preserved. Invoke for "refactor X", "clean up the Y module", or "extract Z" where no behaviour change is intended.

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

---


# Refactor a module

A refactor changes structure, not behaviour. The contract: tests are green before you
start and green after, with no scope creep into new features or fixes.

## Steps

1. **Establish the safety net.** Run the suite first (`run-tests`) and confirm it's green.
   If the module under refactor is thinly tested, add characterization tests (the
   `add-unit-test` skill) that pin the current behaviour before you touch anything.
2. **Read the lore.** Call `search_lore` (Memory MCP) for the repo's module
   boundaries, layering, and naming conventions so the new structure fits the codebase.
3. **Refactor in small, behaviour-preserving steps** — extract, rename, move, dedupe —
   re-running tests after each step. Keep the public interface stable unless the ticket
   explicitly allows changing it; update call sites if you do.
4. **Change no behaviour.** No new features, no bug fixes, no dependency changes riding
   along. If you spot a real bug, note it for a separate ticket — don't fix it here.
5. **Confirm green after.** Run the full suite and lint (`run-tests`, `run-lint`) and
   confirm identical behaviour and no new failures.
6. **Evidence:** before/after passing summaries (proving behaviour preserved) and a
   `diff_summary`. Then use the `record-evidence` skill and submit for review.

## Rules

- Behaviour-preserving only: tests green before and after, same outcomes.
- No scope creep — no features, fixes, or dependency bumps in a refactor ticket.
- Keep the public interface stable unless the AC says otherwise.
- If you uncover a bug, log it separately; don't fix it inside the refactor.
- Run on a branch (the `create-branch` skill), never a protected branch.