Refactor planning

Refactor Planning

Purpose

Plan a refactor that improves structure or quality without changing external behavior, in small reversible steps backed by tests. Produces a refactor work item in ../../work-items/refactors/.

When to Use

• Request classified as refactor, or cleanup enabling later work.
• Not when behavior should change (that's feature-planning) or when fixing a defect (bug-investigation).

Inputs

• The target code and its current tests.
• The improvement goal (readability, decoupling, performance-neutral cleanup).

Discovery Questions

• What is the concrete improvement goal, and how is "better" judged?
• Does adequate test coverage exist to prove behavior is preserved?
• What is the blast radius; who depends on this code?
• Can it be done in small, independently verifiable steps?

Responsibilities

• Audit the target and its dependents.
• Confirm/establish test coverage before touching risky areas.
• Plan small, reversible, behavior-preserving steps.
• Define verification that behavior is unchanged at each step.
• Record the refactor work item.

Required Workflow

1. Read the target + dependents + tests.
2. If coverage is inadequate, plan to add characterization tests first.
3. Break the refactor into small reversible steps.
4. Define per-step verification (tests green, behavior identical).
5. Record the work item (steps, risk, verification).

Decision Rules

• Behavior-preserving by definition — any behavior change reclassifies as a feature.
• Add tests before refactoring under-covered risky code.
• Prefer many small steps over a big-bang rewrite.
• If risk is high and value low, recommend deferring.

Rules

• Do not change observable behavior.
• Keep each step independently verifiable and revertible.
• Preserve public contracts unless the plan explicitly versions them.

Anti-Patterns

• Big-bang rewrite with no rollback path.
• Refactoring untested, risky code without adding tests first.
• Slipping behavior changes into a "refactor."

Validation Checklist

• Improvement goal explicit.
• Coverage confirmed or characterization tests planned.
• Steps small and reversible.
• Per-step verification defined.
• Behavior-preservation guaranteed by tests.

Definition of Done

A recorded refactor work item with a clear goal, sufficient test coverage (or a plan to add it), small reversible steps, and per-step verification proving behavior is unchanged.

Related Skills

existing-project-audit, testing-strategy, task-planning, code-review, performance-review (if perf-motivated), project-orchestrator.

Related Knowledge

../../knowledge/ (module contracts, invariants).

Related References

../../references/<topic>/ for patterns if needed.

Context Loading Guidance

• Requires: target code, dependents, current tests, the goal.
• Does not require: unrelated modules, the full reference tree, unrelated skills.
• May load: testing-strategy (coverage), performance-review (if perf-driven).
• Stop when: steps + verification are recorded.

Token Efficiency Guidance

Scope reading to the target and its direct dependents. Capture steps tersely; rely on tests as the verification record rather than prose.