---
name: refactor-without-behaviour-change
description: "Plans a refactor in small safe steps and names the tests that must pass before and after, so behaviour is proven unchanged rather than assumed. Use when code needs restructuring such as extracting, renaming or splitting, and the team must show that its behaviour did not change. Do not use for adding features, fixing bugs or rewriting a module in a new design. Related topics: coding, technical."
---

# Refactor Without Behaviour Change

Plans a refactor in small safe steps and names the tests that must pass before and after, so behaviour is proven unchanged rather than assumed.

## When to use

Use this skill when code needs restructuring such as extracting, renaming or splitting, and the team must show that its behaviour did not change. Do not use it for adding features, fixing bugs or rewriting a module in a new design.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. List the behaviour that must stay identical, including side effects, error cases and anything callers depend on.
3. Compare existing tests with that list and name each behaviour that has no test.
4. Specify characterisation tests for the gaps and require them to pass on the untouched code before any change.
5. Break the work into named single moves of the requested size, each followed by the exact test run that proves it safe.
6. State what cannot be proven by tests, such as timing or concurrency, and how to check it by hand.

## Inputs

- **Code to refactor** (longer free text)
- **Why it needs to change** (longer free text)
- **Language and test framework** (free text, e.g. "Python with pytest")
- **Existing tests** (longer free text)
- **Risk tolerance** (choose one: Very cautious, Balanced, Move fast)
- **Size of each step** (number from 1 to 20)

## Output

A behaviour list, a table of test gaps, the characterisation tests to add, an ordered step plan with a test checkpoint per step, and a short list of unproven risks.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Refactor Without Behaviour Change

Plan a refactor that changes structure but not behaviour.

- Code to refactor: {{Code to refactor}}
- Why it needs to change: {{Why it needs to change}}
- Language and test framework: {{Language and test framework}}
- Existing tests: {{Existing tests}}
- Risk tolerance: {{Risk tolerance}}
- Size of each step: {{Size of each step}}

Start by writing down the behaviour that must stay identical: inputs, outputs, side effects, errors and timing the callers rely on. Then check the existing tests against that list and name the gaps. Before any code moves, specify characterisation tests that pin the current behaviour, including odd cases, and say they must pass on the untouched code first. Break the refactor into steps of the stated size, each one a single named move such as extract function, rename, or inline, with the test run that follows it. Order steps so the code compiles and the tests pass after every one. Finish with a final comparison check and a list of anything that could not be proven, such as concurrency or performance.

## Pitfalls

- Writing the new tests against the refactored code, which pins the new behaviour and proves nothing about the old.
- Bundling a rename with a logic tweak in one step, so a failing test no longer points at one cause.
- Ignoring side effects such as logging order or database writes, which callers often rely on without knowing.