Skip to content
Skills Library
Programming · Building & coding

refactor

/refactor

Refactor without changing behavior. Use when asked to restructure, extract, move, or split code, or when a review hands over a structural fix. Not for readability (clean-code) or adding behavior (write-plan, tdd).

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Refactor without changing behavior. Use when asked to restructure, extract, move, or split code, or when a review hands over a structural fix. Not for readability (clean-code) or adding behavior (write-plan, tdd).

Original author description

Refactor without changing behavior. Use when asked to restructure, extract, move, or split code, or when a review hands over a structural fix. Not for readability (clean-code) or adding behavior (write-plan, tdd).

How it works

  1. Steps
  2. Referencing
Original SKILL.md headings · 58 lines, 754 words
SKILL.md preview
---
name: refactor
description: Refactor without changing behavior. Use when asked to restructure, extract, move, or split code, or when a review hands over a structural fix. Not for readability (clean-code) or adding behavior (write-plan, tdd).
---

# Refactor

Move **structure** with **behavior locked**. The net is a test green before the move and green after — never a judgment that "this looks the same."

Behavior is settled here, and that is what lets you touch structure without a spec or a plan. You enter at a behavior-preserving structure change, asked for directly or handed over by [qc](../qc/SKILL.md), [architecture-audit](../architecture-audit/SKILL.md), [clean-code](../clean-code/SKILL.md), or [tdd](../tdd/SKILL.md)'s post-green pass. You bypass [write-specs](../write-specs/SKILL.md) and [write-plan](../write-plan/SKILL.md) — there is no new behavior to specify or route.

A refactor that changes observable behavior is a bug wearing a refactor's clothes. The test net is what catches it.

## Steps

### 1. Pin the behavior

Before any structure changes, establish a **green net** that captures the behavior under the move.

- A passing test already covers the behavior → use it.
- No test covers it → write a **characterization test** that captures the behavior as it is today, not as it should be, and run it green. This is not red-green: the test encodes current behavior, bugs and all, because the move must not change it.
- No runnable check exists at all — no test runner, no script, no REPL command that exercises the target → wire the runner the language ships with or the repo already depends on, then write the characterization test above. Adding a new dependency is the user's call: ask first, and if they decline, state the absence and stop. You do not move structure blind.
- The target has no observable behavior — nothing calls it, or every call is itself dead → flag it dead and hand to [write-plan](../write-plan/SKILL.md) for deletion. There is nothing to characterize.

Each pinning test, reused or new, asserts a value rather than a shape, per [Writing the test](../tdd/SKILL.md#writing-the-test). For a characterization test, the known-good literal is today's output, captured by running the code once. Before the first move, prove each pinning test can fail: change its expected literal, run it **red**, restore the literal, run it green. A test that stays green with its literal changed is no net; rewrite its assertion until it goes red.

**Done when** a green test pins every behavior the move touches and each one has gone **red** with its expected literal changed, or the target is flagged dead, or the user declined a runner.

### 2. Move the structure

Execute the move: a **rename**, an **extraction**, or a **reorder** — the vocabulary [clean-code](../clean-code/SKILL.md) uses, at the scale [qc](../qc/SKILL.md) would recommend. One move at a time; run the net after each. Green stays green between moves.

A move that cannot finish with the net green stops here — it is not behavior-preserving, and you are at step 3's decline.

**Done when** the structural move is complete and the net is green after every move in it.

### 3. Gate behavior

Run the full net — the characterization tests plus every pre-existing test in scope. The behavior captured in step 1 must reproduce exactly.

- Green → the move held behavior. Proceed.
- Red → the move changed behavior. **Revert that move.** Do not adjust the test to make it pass: a test edited to match new behavior is the net disabled, and the red is the net doing its job.

A move that needs new or changed behavior to make sense — a new branch, a different return on some input, behavior that was not there before — is **declined**, not forced. That is not a refactor; it is new behavior, and it enters the chain at [write-plan](../write-plan/SKILL.md), worked as [tdd](../tdd/SKILL.md). Hand it over with the structural goal named; the plan can carry both.

**Done when** the net is green end to end and no move in this pass introduced behavior, or the behavior-changing move has been declined and handed to write-plan.

### 4. Hand to qc

Structure moved, behavior held, net green: hand the change to [qc](../qc/SKILL.md) to review the **new structure** — the move may be behavior-preserving and still be ugly, mislayered, or indirected past readability. qc is the axis for that; refactor is not.

**Done when** the change is handed to qc with the move named and the net result recorded.

## Referencing

Where an effort directory exists for the change, the refactor records its net and result there as `<name>.refactor.md`, under the [referencing convention](../write-specs/SKILL.md#referencing). Where none exists, the result goes to chat and the net is the repo's tests; refactor bypasses write-specs and write-plan, so it never creates one.

```markdown
pinned behavior [`db.test.ts:12`](../../../src/db.test.ts#L12)
handed to qc [`qc`](../qc/SKILL.md)
```

Versions

RepositoryScoreLicence
This page · j0hanz/j0hanz-marketplace100MIT
froglet-studio/cosmic-shore100MIT
mgiovani/cc-arsenal100MIT
jongio/skills100MIT
boshu2/agentops100Apache-2.0
y-miyazaki/terraform-aws-base100Apache-2.0
mickeyyaya/evolve-loop100Apache-2.0
kriscard/kriscard-claude-plugins100MIT
kriscard/Skills100MIT

Database snapshot: 13.11.2026 · package version cf5012f8cbbc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100refactor-module
    Use when a ticket asks to restructure code without changing what it does — extract a function, split a file, rename for clarity, reduce duplication — with behaviour preserved. Invoke for "refactor X", "clean up the Y module", or "extract Z" where no behaviour change is intended.
  • 100dev-refactor
    Use when changing structure without changing behavior: restructure, extract, rename, dedupe or split code.
  • 100safe-refactor
    Refactor JavaScript/TypeScript or Python code without changing behavior — extract functions, rename, split large files, remove duplication, modernize syntax, add types — with tests as a safety net. Use whenever the user asks to refactor, clean up, simplify, "rapikan kode",…
  • 90refactor-safely
    Refactor code without changing what it does (rename, extract, split files, remove duplication, simplify). Use when the user says "clean this up", "refactor", "split this file", "simplify this function", "rename X everywhere", or "remove this duplication".
  • 100refactor-safely
    Restructure, rename, split or move code without changing behaviour, and prove that nothing changed. Use this for any refactor, cleanup, file move, module split or dead code removal, including when it is only one step inside a larger task.
  • 100acp-refactor
    Use when the user asks to refactor, clean up, simplify, modularize, deduplicate, rename, or improve the structure of existing code WITHOUT changing behavior. If the user wants new behavior, do not use this skill. Enforces small reversible steps and behavior preservation.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.