Refactor spec
Refactors are where "just clean it up" goes to die. This template treats restructuring as what it is — a behavior-preserving transformation that must be proven equivalent, staged so each step is independently shippable.
Any restructuring larger than a single file: module extraction, layering changes, framework-internal upgrades, dead-code removal at scale, testability improvements. If someone could reasonably ask "did this change behavior?", write the spec that answers "no — and here's the proof."
Section-by-section, annotated
§1 Motivation & current-state analysis
What's wrong with the code as-is, measured: complexity metrics, duplication, defect history, onboarding cost. A refactor without a measured problem is redecoration. Good looks like: numbers that will improve, stated up front.
§2 Target design
The end state: module boundaries, interfaces, patterns, file layout. Precise enough that the diff can be checked against it. Good looks like: a reviewer can look at the final tree and confirm it matches the drawing.
§3 Behavior-preservation guarantees
The heart of the spec: exactly what must not change, and how equivalence will be proven — existing tests, characterization tests, shadow runs, contract tests. Good looks like: a test suite that would catch any behavioral drift, run before and after.
§4 Explicit behavior changes
Refactors sometimes intentionally change behavior (fixing a latent bug, dropping dead paths). Those changes are listed here, approved separately — never smuggled inside "cleanup." Good looks like: an empty section, or a short, deliberate list.
§5 Staged rollout
The refactor broken into independently shippable, independently verifiable steps. Each stage leaves the codebase working and tested. Good looks like: the team could stop after any stage and still be better off.
§6 Risks & abort criteria
What could go wrong per stage, and the conditions under which the refactor stops and reverts. Decided now, not mid-crisis. Good looks like: named tripwires, not vibes.
Copy it, stage it, prove it
# Refactor Spec: [What is being restructured] | Field | Value | |---------|--------------------| | Owner | [Name] | | Status | Draft / In review / Approved / Refactoring / Done | | Created | [YYYY-MM-DD] | ## Revision block | Rev | Date | Author | Description | |-----|------------|--------|------------------------| | 0.1 | [YYYY-MM-DD] | [Name] | Initial draft | ## 1. Motivation and current-state analysis [What's wrong with the code as-is. Measure it:] - **Complexity:** [e.g. cyclomatic complexity, file sizes, nesting depth] - **Duplication:** [Where the same logic lives in N places] - **Defect history:** [Bugs traced to this area in the last 6 months] - **Cost:** [Onboarding time, change lead time, review friction] ## 2. Target design [The end state: module boundaries, interfaces, patterns, file layout. Include a before/after structural sketch.] **Design principles applied:** - [e.g. Single responsibility per module] - [e.g. Dependency direction: X may depend on Y, never the reverse] ## 3. Behavior-preservation guarantees **Must not change:** - [Public API surfaces and their contracts] - [Observable behavior: outputs for given inputs] - [Performance characteristics within X%] **How equivalence will be proven:** - [ ] [Existing test suite — must stay green throughout] - [ ] [Characterization tests written before touching code] - [ ] [Shadow / dual-run comparison, if applicable] - [ ] [Contract tests for affected interfaces] ## 4. Explicit behavior changes (if any) [Intentional behavior changes get listed here and approved separately. If none: write "None — this refactor is strictly behavior-preserving."] - [ ] [Change]: [Why it's safe / who approved] ## 5. Staged rollout ### Stage 1 — [e.g. Extract module boundaries without moving code] - Steps: [Concrete steps] - Verify: [Tests / checks that prove this stage] - Shippable: [Yes — codebase works and is improved at this point] ### Stage 2 — [e.g. Move code into new structure] - Steps: [Concrete steps] - Verify: [Tests / checks] ### Stage 3 — [e.g. Delete dead code, finalize interfaces] - Steps: [Concrete steps] - Verify: [Tests / checks + final equivalence run] ## 6. Risks and abort criteria | Risk | Stage | Tripwire | Action | |------|-------|----------|--------| | [e.g. hidden coupling surfaces] | [1] | [Test failures beyond X] | [Stop, revert stage, re-spec] | ## 7. Done when - [ ] All stages complete and verified - [ ] Behavior-preservation suite green on final state - [ ] Metrics from §1 improved by [target]: [metric] from [before] to [after] - [ ] No new lint / type / coverage regressions
| Rev | Date | Description |
|---|---|---|
| 1.0 | 2026-09-20 | Initial publication. |
← Prev: Migration spec · Gallery · Next: Architecture decision record →