# Refactor

> Use this skill ALWAYS whenever improving code structure without changing externally visible behavior — renaming, extracting, simplifying, deduplicating, reorganizing modules. Trigger this skill EVEN if user just says "clean up X" or "improve Y" without mentioning the refactor process.

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

---


# Refactor workflow

Refactor = improving structure WITHOUT changing externally visible behavior.

## 1. Identify exact scope
- Files involved (use Glob/Grep/Serena `find_references`)
- External interface (public API, exported functions, DB schema, HTTP routes)
- Internal-only structure that can change

## 2. State invariants (must NOT change)
- HTTP API contract (paths, params, response shape)
- Public function signatures
- DB schema (unless this IS a schema migration)
- Test outputs (existing tests must still pass)

Write invariants to `.claude-data/invariants-session.md` so PreCompact preserves them.

## 3. Small reversible changes (R12 per task)
- ONE change at a time
- After EACH change: run tests + mypy + ruff
- If a change breaks something → revert that one change, not the whole work
- Commit-able state at every step (even if you don't commit)

## 4. Update navigation if needed
- If files moved → update `docs/agent/05_module_map.md`
- If new module created → add to module map
- If responsibility shifted between modules → update both

## 5. ADR if architectural boundary changes
- Moved auth logic from `api/` to dedicated `auth/` package = architectural = ADR
- Renamed function = not architectural = no ADR
- Reorganized internal helpers = not architectural = no ADR

## 6. Do NOT mix in feature work (R3)
- If you see a bug while refactoring — log to `docs/agent/06_known_issues.md`, do not fix in this commit
- If you see a missing feature — log to backlog, do not add
- Refactor commit must be reviewable as "structure only"

## Anti-patterns
- ✗ "Big bang" refactor of 30+ files in one session
- ✗ Mixing rename + bugfix + new feature in one commit
- ✗ Refactoring without running tests (assumed they'll pass)
- ✗ Renaming public API without checking call sites