Refactor
Concept of the skill
Behavior-preserving restructuring of existing code — extracting functions, reducing duplication, renaming for clarity, splitting modules, and tightening structure, with every change verified against before/after behavior so external contracts stay identical.
Coverage
- Behavior preservation: identifying the external contract that must remain stable before any change
- Duplication reduction: consolidating repeated logic without over-abstraction
- Decomposition: extracting functions, modules, or types to improve readability and reuse
- Naming improvements: renaming so identifiers carry their real meaning
- Structure improvements: reorganizing file and module boundaries when the current layout obscures intent
- Verification before and after: running the same behavioral checks on both sides of the change
Philosophy of the skill
Refactoring pays off only when the shape of the code has diverged from the shape of the problem. Before that point it is risk without reward — every move invites a regression, and "cleaner" is a preference, not a justification. The honest test for a legitimate refactor is not "this feels better" but "the next concrete change will be materially easier because of this one." If you cannot name the next change, stop — you are rearranging, not refactoring, and the safest rearrangement is none.
Workflow
Each step decides whether to continue, split, or stop. "Stop" is always a valid answer; speculative refactoring is a failure mode, not a signal of ambition.
| Step |
Ask |
If yes |
If no |
| 1. Contract |
What externally observable behavior must stay the same? |
Write it down as a test suite or explicit checklist |
Stop — you cannot refactor what you cannot pin down |
| 2. Next-change justification |
Can you name one concrete pending change that becomes easier because of this refactor? |
Go to step 3 |
Stop — you are rearranging for taste, not improving the codebase |
| 3. Smallest useful cut |
What is the smallest structural change that moves toward the next-change goal? |
Make only that change |
Split into sequential cuts; do not change multiple abstraction layers at once |
| 4. Behavior re-verify |
Does the contract from step 1 still hold exactly? |
Commit |
Revert; the refactor was not behavior-preserving. Start over smaller |
| 5. Stop condition |
Have you made the next change materially easier than it would have been before? |
Done |
Do not keep going — refactoring beyond the next change is speculative waste |
When to back out
- A green test from before the refactor is now red → revert immediately, then cut smaller.
- The next-change goal shifted during the refactor → restart at step 2 with the new goal before continuing.
- The refactor requires touching more than one abstraction layer in a single commit → split into per-layer commits and re-verify each.
Evals
This skill ships a comprehension-eval artifact at examples/evals/refactor.json. The Verification checklist below is the authoring gate for a completed refactor; the eval file is how this skill is graded by scripts/skill-audit.js --graded. Do not conflate them — the checklist is for the engineer, the eval is for the grader.
Verification
Do NOT Use When
| Use instead |
When |
debugging |
The task starts from a failing behavior, not from structural cleanup |
documentation |
The task is rewriting docs — even docs about the refactored code — it belongs to a separate commit and skill |
testing-strategy |
The task is designing a new test suite; the refactor's own tests should already exist before step 1 |
Skill Graph context
Classification
- Subject:
software-engineering-method
- Public:
true
- Scope: Behavior-preserving restructuring of existing code — extracting functions, reducing duplication, renaming for clarity, splitting modules, and tightening structure, with every change verified against before/after behavior so external contracts stay identical. Portable across any language or codebase; principle-grounded, not repo-bound. Excludes bug investigation and root-cause isolation (debugging, diagnosis), adding new product behavior (feature implementation), and documentation authoring (doc-updater) even when the docs describe the refactored code.
When to use
- this 600-line function is hard to reason about — decompose it while keeping tests green
- extract the duplicated validation logic from these three handlers into a helper
- rename this module from
utils to something that describes what it actually does
- split this file by responsibility; no behavior changes, tests must still pass
- Triggers:
refactor-skill
Not for
- the test is failing after my edit — what did I break?
- write an architecture note explaining this pattern for new team members
- reproduce why this function retries three times on transient network errors
Related skills
- Depends on:
testing-strategy
- Verify with:
testing-strategy, test-driven-development, test-doubles-design
- Related:
semantics, tool-call-flow, generative-ui, context-graph, error-boundary, performance-testing
Keywords
refactor, cleanup, extract function, reduce duplication, rename module, rename for clarity, split this file, decompose function, duplicated logic, behavior preserving
1---2name: refactor3description: Use when reorganizing existing code without changing external behavior — extracting functions, reducing duplication, renaming for clarity, splitting modules, or tightening structure. Covers behavior preservation, duplication reduction, decomposition, naming improvements, structural reorganization, and before/after verification. Do NOT use for bug investigation, adding new product behavior, or writing documentation (even when the docs describe the refactored code). Do NOT use for the test is failing after my edit — what did I break? Do NOT use for write an architecture note explaining this pattern for new team members. Do NOT use for reproduce why this function retries three times on transient network errors.4license: MIT5---6# Refactor78## Concept of the skill910Behavior-preserving restructuring of existing code — extracting functions, reducing duplication, renaming for clarity, splitting modules, and tightening structure, with every change verified against before/after behavior so external contracts stay identical.1112## Coverage1314- Behavior preservation: identifying the external contract that must remain stable before any change15- Duplication reduction: consolidating repeated logic without over-abstraction16- Decomposition: extracting functions, modules, or types to improve readability and reuse17- Naming improvements: renaming so identifiers carry their real meaning18- Structure improvements: reorganizing file and module boundaries when the current layout obscures intent19- Verification before and after: running the same behavioral checks on both sides of the change2021## Philosophy of the skill22Refactoring pays off only when the shape of the code has diverged from the shape of the problem. Before that point it is risk without reward — every move invites a regression, and "cleaner" is a preference, not a justification. The honest test for a legitimate refactor is not "this feels better" but "the next concrete change will be materially easier because of this one." If you cannot name the next change, stop — you are rearranging, not refactoring, and the safest rearrangement is none.2324## Workflow2526Each step decides whether to continue, split, or stop. "Stop" is always a valid answer; speculative refactoring is a failure mode, not a signal of ambition.2728| Step | Ask | If yes | If no |29|---|---|---|---|30| 1. Contract | What externally observable behavior must stay the same? | Write it down as a test suite or explicit checklist | Stop — you cannot refactor what you cannot pin down |31| 2. Next-change justification | Can you name one concrete pending change that becomes easier because of this refactor? | Go to step 3 | Stop — you are rearranging for taste, not improving the codebase |32| 3. Smallest useful cut | What is the smallest structural change that moves toward the next-change goal? | Make only that change | Split into sequential cuts; do not change multiple abstraction layers at once |33| 4. Behavior re-verify | Does the contract from step 1 still hold exactly? | Commit | Revert; the refactor was not behavior-preserving. Start over smaller |34| 5. Stop condition | Have you made the next change materially easier than it would have been before? | Done | Do not keep going — refactoring beyond the next change is speculative waste |3536### When to back out3738- A green test from before the refactor is now red → revert immediately, then cut smaller.39- The next-change goal shifted during the refactor → restart at step 2 with the new goal before continuing.40- The refactor requires touching more than one abstraction layer in a single commit → split into per-layer commits and re-verify each.4142## Evals4344This skill ships a comprehension-eval artifact at [`examples/evals/refactor.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/refactor.json). The `Verification` checklist below is the authoring gate for a completed refactor; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the engineer, the eval is for the grader.4546## Verification4748- [ ] External behavior is unchanged — same tests green before and after49- [ ] The named next change is now demonstrably easier, not merely "more possible"50- [ ] No new abstraction was introduced speculatively (no "future-proofing" without a named consumer)51- [ ] Each commit is a single structural change, not a bundle of rearrangements5253## Do NOT Use When5455| Use instead | When |56|---|---|57| `debugging` | The task starts from a failing behavior, not from structural cleanup |58| `documentation` | The task is rewriting docs — even docs about the refactored code — it belongs to a separate commit and skill |59| `testing-strategy` | The task is designing a new test suite; the refactor's own tests should already exist before step 1 |6061## Skill Graph context6263<!-- skill-graph-context:start (generated — do not edit by hand) -->6465**Classification**66- Subject: `software-engineering-method`67- Public: `true`68- Scope: Behavior-preserving restructuring of existing code — extracting functions, reducing duplication, renaming for clarity, splitting modules, and tightening structure, with every change verified against before/after behavior so external contracts stay identical. Portable across any language or codebase; principle-grounded, not repo-bound. Excludes bug investigation and root-cause isolation (debugging, diagnosis), adding new product behavior (feature implementation), and documentation authoring (doc-updater) even when the docs describe the refactored code.6970**When to use**71- this 600-line function is hard to reason about — decompose it while keeping tests green72- extract the duplicated validation logic from these three handlers into a helper73- rename this module from `utils` to something that describes what it actually does74- split this file by responsibility; no behavior changes, tests must still pass75- Triggers: `refactor-skill`7677**Not for**78- the test is failing after my edit — what did I break?79- write an architecture note explaining this pattern for new team members80- reproduce why this function retries three times on transient network errors8182**Related skills**83- Depends on: `testing-strategy`84- Verify with: `testing-strategy`, `test-driven-development`, `test-doubles-design`85- Related: `semantics`, `tool-call-flow`, `generative-ui`, `context-graph`, `error-boundary`, `performance-testing`8687**Keywords**88- `refactor`, `cleanup`, `extract function`, `reduce duplication`, `rename module`, `rename for clarity`, `split this file`, `decompose function`, `duplicated logic`, `behavior preserving`8990<!-- skill-graph-context:end -->
jacob-balslev