---
name: refactor
description: "Behavior-preserving refactor workflow adapted for LazyClaude: characterize first, split safely, preserve public contracts, and verify through tests plus real surface evidence."
---

# Refactor

Use this skill for behavior-preserving restructuring. A refactor changes shape,
not observable behavior. If behavior changes, it is a feature or bug fix and
needs its own RED test.

## Refactor Contract

Before editing:

- Name the behavior that must remain unchanged.
- Write or identify characterization tests.
- Capture the current output, CLI behavior, hook JSON, or plugin manifest shape.
- Decide the smallest cohesive unit to move, split, rename, or simplify.

## Characterization First

A characterization test pins current behavior before changes. It should assert
the contract, not incidental formatting. For LazyClaude, good contracts include:

- CLI command succeeds or fails with a controlled message.
- hook JSON contains the expected activation context.
- plugin manifest exports the expected commands, skills, agents, MCP, and LSP.
- install state preserves unrelated Claude settings.
- docs contain required install and publish guidance.

Run the characterization test before refactoring and record that it passes.

## Safe Splits

Split by responsibility:

- parsing
- registry/state reads
- registry/state writes
- command dispatch
- hook context construction
- docs-only policy
- QA scripts

Avoid splitting by arbitrary line ranges. A new file must have a clear owner.

## Prohibited Moves

- Do not rename public CLI commands without compatibility aliases.
- Do not change plugin keys such as `lazyclaude@lazyclaude-ai` silently.
- Do not alter install paths without migration tests.
- Do not hide behavior changes inside refactor commits.
- Do not delete tests to make a refactor pass.

## Verification

After refactoring:

1. Run targeted characterization tests.
2. Run the full relevant suite.
3. Run one real-surface scenario if the refactor touches install, hooks, or CLI.
4. Compare before/after outputs where practical.
5. Record cleanup for spawned resources.

## Review Checklist

- Public behavior unchanged.
- Error messages still actionable.
- Package `files` allowlist still includes moved files.
- Docs still reference the right paths.
- Tests fail if the behavior regresses.
- No generated or user-owned state was rewritten unexpectedly.
