refactoring

name	refactoring
description	Change the shape of code without changing behavior — safely, in small steps, preserving the project's layers and public contracts.
generated	true
source	.ai/skills/refactoring.md

Skill: Refactoring

Purpose

Change the shape of code without changing its behavior, safely and in small steps, while preserving the project's layers and public contracts.

When to Use This Skill

• Improving structure, naming, or readability of existing code.
• Extracting a function/module, splitting a large file, or removing duplication.
• Preparing code for a feature by reshaping it first.
• Reducing complexity flagged during code/architecture review.

Files to Read First

• AGENTS.md (boundaries and "no large uncontrolled rewrites").
• .ai/skills/architecture-review.md (invariants you must preserve).
• The tests covering the code you intend to change.
• Any doc/ADR describing the contracts the code implements.

Core Principles

• Preserve public behavior. A refactor changes structure, not observable behavior or contracts.
• Tests first for risky changes. If coverage is thin, add characterization tests before refactoring.
• Small steps. Many tiny, verified changes beat one big rewrite.
• Stay in scope. Do not refactor unrelated code you happen to pass by.
• Don't collapse layers for convenience, and don't introduce circular dependencies.
• Rename concepts deliberately. Update docs/ADRs/tests when a name changes.
• Prefer simple extraction over introducing complex patterns.

Process

1. Define the goal and boundary. State exactly what improves and which files are in scope.
2. Ensure a safety net. Confirm or add tests that pin current behavior.
3. Refactor in small steps, running make test after each meaningful step.
4. Keep layers intact. Verify the change respects architecture invariants.
5. Update names everywhere. If a concept is renamed, fix code, tests, and docs in the same change.
6. Keep commits logically scoped (one refactor idea per commit).
7. Final validation. Run make check; diff should be structure-only.

Checklist Before Finishing

• Public behavior and contracts unchanged (tests still pass unmodified, or changes are justified).
• Tests existed/were added before risky changes.
• Change is scoped; no unrelated code touched.
• No layer collapsed; no circular dependency introduced.
• Renamed concepts updated across code, tests, and docs.
• Commits are small and logically scoped.
• make check passes.

Common Mistakes to Avoid

• "While I'm here" edits to unrelated code (scope creep).
• Refactoring without a test safety net.
• One giant commit mixing behavior changes with restructuring.
• Renaming a concept in code but not in docs/ADRs.
• Introducing a clever pattern where a simple extraction suffices.
• Creating import cycles by moving code carelessly.

Expected Final Report

State: the goal of the refactor and its scope; the safety net used (existing or added tests); the small steps taken; confirmation that public behavior/contracts are unchanged and layers are intact; any renamed concepts and where they were updated; and the make check result.