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

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/refactoring.md and run `make generate-ai`.
-->

# 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.