Skip to content
Skills Library
Programming · Analysis

refactor-pass

/refactor-pass

Find what in a git repo needs refactoring, and what doesn't, the way developers used to feel it while coding by hand. It measures where changes keep landing (a heatmap of git history), what makes those files hard to change (code smells, each with its playbook of named refactorings) and what the next change would cost, then ranks refactors on a checklist worked through one item at a time. Use it whenever the user asks for a refactor pass; asks about tech debt, code health, hot spots or cleaning up; asks for refactor opportunities, or code that's cleaner, more maintainable, scalable or SOLID; as

Licence
MIT
Last repository change
12.11.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
9
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/check_page.py, scripts/heatmap.py, scripts/measure.py, scripts/scoping.py

What it does and when to use it

Find what in a git repo needs refactoring, and what doesn't, the way developers used to feel it while coding by hand. It measures where changes keep landing (a heatmap of git history), what makes those files hard to change (code smells, each with its playbook of named refactorings) and what the next change would cost, then ranks refactors on a checklist worked through one item at a time. Use it whenever the user asks for a refactor pass; asks about tech debt, code health, hot spots or cleaning up; asks for refactor opportunities, or code that's cleaner, more maintainable, scalable or SOLID; as

Original author description

Find what in a git repo needs refactoring, and what doesn't, the way developers used to feel it while coding by hand. It measures where changes keep landing (a heatmap of git history), what makes those files hard to change (code smells, each with its playbook of named refactorings) and what the next change would cost, then ranks refactors on a checklist worked through one item at a time. Use it whenever the user asks for a refactor pass; asks about tech debt, code health, hot spots or cleaning up; asks for refactor opportunities, or code that's cleaner, more maintainable, scalable or SOLID; as

How it works

  1. 1. Where: the heatmap
  2. 2. What: the smells
  3. 3. How much: the walkthrough
  4. 4. Check every finding
  5. 5. Rank
  6. 6. Write the checklist and report
  7. 7. Working through the list
  8. After an earlier pass
Original SKILL.md headings · 379 lines, 3,639 words
SKILL.md preview
---
name: refactor-pass
description: Find what in a git repo needs refactoring, and what doesn't, the way developers used to feel it while coding by hand. It measures where changes keep landing (a heatmap of git history), what makes those files hard to change (code smells, each with its playbook of named refactorings) and what the next change would cost, then ranks refactors on a checklist worked through one item at a time. Use it whenever the user asks for a refactor pass; asks about tech debt, code health, hot spots or cleaning up; asks for refactor opportunities, or code that's cleaner, more maintainable, scalable or SOLID; asks what the worst part of the codebase is; says "we've made a lot of changes, anything to refactor?" or "before we start on the next feature, anything to fix first?"; or asks about one area ("should we refactor X?", "is this class doing too much?"). Use it even when they don't mention smells or churn. Also use it to carry on with a checklist this skill made ("what's next on the list", "start R4").
license: MIT
---

# Refactor pass

Refactoring used to start with a feeling. Code was hard to work on: a class
you scrolled through to find where the new thing went, a function you held
in your head to change one branch, a feature that meant visiting eight
files. The same feeling told you what to leave alone. Ugly code you never
touched never hurt, so you let it be.

An agent writing code doesn't feel any of that, and neither does a developer
who mostly reads what the agent wrote. So smells pile up unnoticed. An agent
will add a thirtieth branch to a function without complaint. And when it's
asked to refactor, it tidies whatever looks untidy, including code nobody
touches. This skill gives back both halves of the feeling, as three things
you can measure:

1. **Where you'd feel it: the heatmap.** Friction only matters where changes
   keep landing. Across studies, file size and how often a file changes
   predict maintenance trouble better than any single smell.
2. **What you'd feel: the smells.** The established catalogue of smells,
   each translated into what to count, when it *isn't* a smell, and the
   playbook of named refactorings that decades of practice built for it:
   [references/smells.md](references/smells.md).
3. **How much you'd feel it: the walkthrough.** Take the next change that's
   coming, planned or likely, and list everything it would touch.

Then the verdict combines where and what:

| | Smells | Doesn't smell |
|---|---|---|
| **Changes often** | Refactor | Say it's fine |
| **Rarely changes** | Leave it; at most a "Later" note | Nothing |

The "say it's fine" box matters as much as the "refactor" one. It's the
restraint half of the intuition, and the report shows it.

**Two sizes of question.** A pass covers the whole repo: steps 1 to 7. A
question about one area ("should we refactor X?") runs the same steps on
that area only. It skips the checklist unless there are several items, and
its answer can be "no". Either way, first run step 1's script with
`--checklists` alone: if it lists a checklist from an earlier pass, read
[After an earlier pass](#after-an-earlier-pass) first.

## 1. Where: the heatmap

```bash
python3 <this skill's directory>/scripts/heatmap.py -C <repo> <scope ...>
```

`<this skill's directory>` is the folder that holds this SKILL.md. Where
`python3` isn't the command, as often on Windows, use `python` or `py`.
If a script stops on a bug in the script itself, as it says, tell the user
what it said, and go on without it, from `git log` and the code.

- **Scope**: the source folders and the tests' folders, such as `src tests`
  or `app`, not docs or assets. Read the project's README, a directory
  listing and any agent instructions (`AGENTS.md`, `CLAUDE.md`) to decide.
  Test files, known by name (`Board.spec.ts`, `test_x.py`, `XTest.php`...)
  or folder, stay out of the table and pairs, and are listed apart when
  they change with several files. Add `--test GLOB` for other test names,
  `--not-test GLOB` for a file that only looks like one (the heatmap names
  any it doubts), and `--ignore GLOB` for generated files.
- **Window**: by default the last 200 commits. `--since` sets it instead
  when the user names a starting point ("since v2.0", "since we added
  billing", "the last three months"): a tag, branch or commit, or a date.
  Left out automatically: housekeeping bots' commits (dependencies,
  releases, formatting; the output names them, and `--bot NAME` adds one),
  the bulk reformats a repo lists in `.git-blame-ignore-revs`, and the
  commits recorded on earlier checklists. Coding agents' commits count.
  `--exclude-commits` leaves out others that would make everything they
  touched look hot, such as a vendored import. Dates are commit dates, as
  `git log --date=short-local --format='%h %cd %s'` shows them, not the
  author dates plain `git log` shows.
- **Too thin?** With fewer than about 30 commits in the window, the counts
  can't tell hot files from cold ones. Widen the window, or say the history
  is too short to point anywhere and judge by the smells alone. A shallow
  clone (the heatmap says so) needs `git fetch --unshallow`; ask the user.

`--help` explains every column and option.

### Reading it

- **A hot spot** has many commits and is also big, so the list puts those
  first: it's ordered by commits times size. Many commits on a small file is
  often fine, like a config edited for each feature. A big file nobody
  touches is cheap to leave alone.
- **Still hot?** `recent` counts its commits in the window's newer half
  (half the commits, not half the time), and `last` is the date of its
  latest. Read both against the window's dates: eight `recent` commits, all
  on the day the newer half starts, are a burst that has cooled. A file
  that shrank may already have been dealt with.
- **`rel`** is lines changed over the file's size. Relative churn predicts
  defects far better than absolute churn. Well above 1 means the file was
  rewritten or grew in the window. Read it with **growth**: a file that only
  grows, commit after commit, is
  [Additive-Only Growth](references/smells.md#additive-only-growth). A file
  born in the window has growth equal to its size.
- **Pairs** are files that keep changing in the same commits. A **group**
  is three or more that all pair with each other, counted by the commits
  that changed them all; groups that overlap are listed together as one
  area. A row's `last` is when its files last changed together: one whose
  last shared commit came before a refactor that took it apart is history,
  not coupling you'd feel today.
  - Files from different layers that pair strongly, or a group across
    layers, usually mean one feature spread across them (Shotgun Surgery).
  - Check what links each pair. An import, a call, or a contract something
    names (a route, a schema, the type file between a controller and its
    page) is a visible dependency: one feature across a boundary. Files
    that change together with no such link, such as two copies of a rule
    or two lists kept in step by hand, have a hidden dependency, the
    strongest kind of coupling.
  - A file that pairs with many others is a hub every change passes through.
  - A test listed as changing with several files besides its own is a lead
    to read: one that reaches their private members or internal paths is
    tied to their internals and will block refactoring; a broad test that
    follows features through them, or only follows a group, isn't.
  - If many commits were too big to pair (`--max-files`), as in a repo that
    squash-merges, raise it or read the pairs as partial.
- **Why it changes.** Read the top few files' commit messages (`--show`)
  and group them by feature. Many unrelated reasons to change one file is
  Divergent Change, and it shows here more directly than in any count.

## 2. What: the smells

- **Measure the hot files** against the codebase itself, within one
  language. `python3 <this skill's directory>/scripts/measure.py -C <repo>
  <scope ...>` puts each file in a band by its language's 70th, 80th and
  90th percentiles, and `--show <file>` each of its functions, with their
  first and last lines. Big is the 80th or 90th band (past the catalogue's
  floor); the 70th is worth a closer look. Where the percentiles lean on
  one big file or function, it says so and bands by the catalogue's
  reference points instead: `>75` or `>440` is big, `>45` or `>220` worth
  a closer look. [Measuring](references/smells.md#measuring) says how to
  count the rest (branches, parameters, cohesion, a function's history),
  or to use the project's linter.
- **Read the top two or three core files yourself.** Numbers point; reading
  decides.
- **Review the other hot areas.** If you can run sub-agents, give two or
  three of them an area each (a layer or a directory, so each reads a whole
  area once) and run them in parallel. Brief each from
  [references/review-brief.md](references/review-brief.md). Without
  sub-agents, review the areas yourself, one at a time, against the same
  brief.
- **Name each smell with its established name** (Long Function, Shotgun
  Surgery, Repeated Switches…), and check it against the entry's "Not a smell
  when" before it counts. The name is the index to its playbook.
- **Look for the missing idea.** Smells travel in clusters, and a cluster
  usually points at one thing the code uses all the time but never named: a
  state, a kind's definition, a single source for a setting. See
  [Smells travel together](references/smells.md#smells-travel-together).
- **Check what tests reach the hot code**: see
  [Untested Code](references/smells.md#untested-code).
- **Bugs you notice** go on the list as F items, not fixed now. A bug not
  yet reproduced is a suspicion: title it as one ("Check: edits skip the
  weekend rule"), with the evidence in its note. Its first step is a
  failing test; if none fails, it's skipped, with what you found. A
  behaviour you reproduced that may be intended is the user's call: an F
  item, `waiting`, titled by what happens ("Refunds keep the fee"), with
  the question in its note; it's fixed if they say it's a bug, and skipped
  with their answer if not.

## 3. How much: the walkthrough

This is the closest thing to the old feeling. It's also what makes an item
convincing.

1. Find the next changes. A planned change beats an inferred one, so take
   them first from what the user said is coming ("before we start on chunk
   7"), then from the project's plan or roadmap, if it has one, then from
   what the code announces (a deprecation notice, a TODO that names a
   version), then from the commit messages: the kinds of change that come
   up most often ("add a new report type", "add a setting", "add a
   screen"). Take the two or three commonest kinds, not just one.
2. For each kind, take the latest real commit of it and list what it
   touched (`git show --stat`). If it's older than the window, use it all
   the same and give its date; the walkthrough, on today's code, shows what
   has moved since. If the project's docs or agent instructions have a
   recipe for that change, count its steps. A five-step recipe for adding
   one thing is an admission.
3. Walk through the next one, without writing it. List every file you'd
   have to read, every place you'd edit, and every copy you'd keep in step.
4. Write down the count today and the count after the refactor you'd
   propose: "a new report type touches 7 files and 3 switches today, and
   would touch 1 file after".

A cold file that planned work will land in is no longer cold: put it in the
table's top row, since the next change pays whatever it costs. If the next
change is cheap today, the smell is costing little, whatever it looks like.

## 4. Check every finding

A reviewer's finding is a lead, not a fact, and the same goes for your own
first impressions. Before anything goes on the list, open the cited lines,
re-run the counts, and drop or correct what doesn't hold. Say in the report
what you checked. A wrong item that sends the user into a refactor costs far
more than the minute it takes to check it.

Then apply the restraint. A reviewer asked to find problems will always find
something, and fixing every finding leaves extra layers and tests for cases
that can't happen. Leave out what's cold, what the "Not a smell when" lines
excuse, and what the walkthrough says is cheap.

## 5. Rank

Give every item a stable ID, because the user will name items by it ("start
R4"), possibly in a later session. IDs are names, not ranks: a carried-over
item keeps its own, so a new R4 can come before R3, and the page lists items
in the order you write them. The names in brackets are the item's fields on
the checklist (step 6); F, L and D items say theirs in a `note`.

- **R1, R2…** Refactors, in the suggested order. For each:
  - a title naming the missing idea, as an outcome ("Name the states of a
    checkout", not "Refactor CheckoutController") (`title`);
  - the smells by name, with numbers and `file:line` (`smells`);
  - the kind of change it eases, from step 3 (`eases`), and that change's
    cost (`cost`: `today` and `after`);
  - the plan, as the playbook's steps (`plan`);
  - the files, size (S, M or L) and risk (Low, Medium or High) (`files`,
    `size`, `risk`);
  - how to check that behaviour didn't change (`verify`).
- **F1…** Small fixes found along the way, each its own commit.
- **L1…** Later: smelly but cold, or worth doing when the code nearby is next
  touched.
- **D1…** The user's call: changes to how they work, such as a docs
  convention that makes every change costly. Lay out the trade-off, not a
  decision.

Rank by payoff against risk. Payoff is how much the change eases future
work: the heatmap and the walkthrough are the evidence. The smells'
priorities say which kinds tend to matter. Long and complex code, and
change spread across files, matter most. Coupling smells such as Feature
Envy and Middle Man matter least, and are
[fixed in passing](references/smells.md#fix-in-passing). A healthy codebase
gets a short list: one refactor, or none, is a result, and "nothing worth
refactoring now" is a finding to report as plainly as any other.

Order the list so that:
- blockers come first: tests tied to internals that would make every later
  step look like it broke something, and code no test covers, whose item
  starts with pinning tests or says plainly it can't be checked (step 7);
- the small items that remove a copy-paste path come next;
- large moves come after, since they often need a seam first;
- anything you can't verify yourself (how it sounds, feels or looks) comes
  last, because the user has to check it.

## 6. Write the checklist and report

Run step 1's command again with `--page` and the name `--checklists` gave:
today's date (`.refactor-pass/2026-11-11.html`, or `2026-11-11-2.html` for a
second pass that day). It makes the checklist from
[assets/page.html](assets/page.html) and writes the heatmap into its
`heatmap` block; on a checklist that exists, it refreshes the heatmap and
nothing else, and says so. You write the `pass` block below it, whose
`project`, `started`, `base` and `updated` are already filled in:

- `summary`: the overall state in two or three sentences;
- `items`: every item, in the suggested order, with step 5's fields, a
  `status` (`todo`, `doing`, `waiting` on the user, `done`, or `skipped`
  with the reason in its outcome), and `commits` and `outcome`, empty for a
  new item; a carried-over item keeps its `from`. An item's first line
  holds its ID and status, `{"id": "R1", "status": "todo",` and its title;
  its other fields go on the lines after, as the comment above the blocks
  shows. Not the whole item on one line, nor a JSON pretty-printer's
  layout: step 7's status updates edit that first line;
- `left_alone`: each with `what` and `why`;
- `checks`: the project's checks, from its instructions, or what you'll
  check by hand if it has none;
- `earlier`: after an earlier pass, `checklist`, its path as
  `--checklists` prints it, and `results`, one per refactor finished on it
  (one that only added pinning tests too): its `id`, `title`, `eases` and
  `cost` as it had them; `change`, the first real change of that kind
  since, as hash, date and subject, and `actual`, what that touched, from
  `git show --stat`, both empty if none has come yet; and a `note` on how
  the prediction held. Otherwise `null`;
- `log`: each with a `date` and `text`, newest first.

After each edit, run `python3 <this skill's directory>/scripts/check_page.py
<page>`, which catches a broken bracket, a misspelt field, a duplicate ID or
an item whose first line isn't its ID and status, and warns of a field left
empty. If your environment can publish or preview HTML pages, publish the
same file and give the link; otherwise give the path to open in a browser.

**Where it lives.** `.refactor-pass/` is at the repo's top, with a
`.gitignore` the heatmap writes, so the folder is never committed and the
project's own `.gitignore` stays untouched. In a linked worktree, a relative
`--page` path is the main checkout's, which outlives the worktree. If a
sandbox won't let you write there, the heatmap says what to do. If the
checklist will go with a worktree or a cloud sandbox, tell the user.

Then reply with:

- after an earlier pass, how its finished items' predictions held;
- two or three sentences on the overall state, good parts included;
- the top three to five hot spots as a small table (file, lines as the
  heatmap's `size` gives them, commits);
- the R items as a numbered list: title, smells, size, risk, and the next
  change's cost today and after;
- the F and D items in brief;
- what you left alone and why, in a line or two;
- the suggested order, and where the checklist is;
- a question: which item should you start with?

Don't change any code until the user picks.

## 7. Working through the list

- **One item at a time, when the user names it.** Read the newest checklist
  first (`--checklists` finds it), including when you're picking up in a
  new session: its plans may be days old.
- **Two hats.** A refactoring step changes structure and no behaviour. Never
  mix it with a fix or a feature, in the same commit or the same step. If you
  find a bug, note it as an F item.
- **Make the change easy, then make the easy change** (Kent Beck). When an
  item exists to make a coming feature easy, finish the refactor before
  starting the feature.
- **Pin untested code first.** Before refactoring code no test covers, write
  characterization tests (Feathers): tests that record what it does now,
  right or wrong, through what its callers use. Commit them on their own. If
  it can't be pinned, say so in the outcome, with the risk; don't call it
  verified.
- **Follow the playbook in small steps.** Use the named refactorings, one at
  a time, with the tests passing after each, and the editor's or language
  tools' automated refactorings where they exist. If the tests stay failing
  for more than a few minutes, go back to the last passing state and take a
  smaller step.
- **Leave alone what you don't need to change**, and wait for the third copy
  before merging copies.
- **Behaviour doesn't change.** Check each step with the project's own
  checks: tests, linters, snapshot or simulation tools, whatever its
  instructions name. Take extra care with hierarchy refactorings (pulling
  methods up, extracting subclasses), which induce bugs most often.
- **Check the smells again after an item.** A refactor can leave a smell
  behind or make a new one: a class that took on moved methods can turn into
  a Large Class.
- **Commit exactly as the project's and the user's rules say.** Some users
  want to approve every commit first.
- **When the plan changes**, because a finding was wrong, a step was dropped
  or something was found on the way, write that in the item's outcome. Don't
  quietly leave it out.
- **After each step, update the checklist** in small edits: the item's
  status (an edit to its first line: `{"id": "R4", "status": "todo"` becomes
  `"doing"`); its `commits`, every hash as it landed on the branch the user
  keeps (after a squash merge or a rebase, the new hashes), so a later pass
  can leave them out; its outcome, with the checks' numbers and the next
  change's cost now; a dated log entry; `updated`; and any `file:line` in
  other items that the step moved. Then run `check_page.py`, and republish
  the page if it was published.
- **Asked "what's next?"**, answer from the checklist. Don't start the work.

## After an earlier pass

`heatmap.py --checklists` lists every checklist, the main checkout's and
any worktree's, newest first by the date in its name and then its number,
and gives the name a new one takes.

1. **Build on the newest.** The heatmap leaves out the commits recorded on
   every checklist, so the refactoring just done doesn't make its own files
   look hot. If it warns that a recorded commit isn't reachable from HEAD
   and the work was squash-merged or rebased, record the hash that landed it
   instead, and run the heatmap again before reading it.
2. **See what has landed since.** `--since <its base>` shows it; when
   that's nothing but the pass's own work, it says so, and so should you.
   Growth, being two sizes, still counts the pass's own commits: a file a
   refactor made or shrank shows growth its churn doesn't explain.
3. **Start a new checklist** under the name `--checklists` gives, even on
   the same day; `--page` on the old one would only refresh its heatmap.
4. **Carry items over.** Items still `todo`, `doing` or `waiting` carry
   over, checked again as any finding is ([step 4](#4-check-every-finding)),
   keeping their IDs and `from`, the date of the checklist they first
   appeared on. Done and skipped items stay behind; done refactors appear in
   `earlier` instead. A Later item that has turned hot becomes a new R item.
   New items number on from the highest ID of each letter.
5. **Check the predictions.** For each refactor finished on the newest
   checklist, find the first real change of the kind it eased after its
   last commit (never one recorded on a checklist), list what it touched
   (`git show --stat`), and set that beside the cost the item predicted, in
   `earlier`. That is the "it's easier now" half of the feeling, so the
   report leads with it, misses included.
Files in this package (9)
  • SKILL.md 22 KB
  • assets/page.html 29 KB
  • references/review-brief.md 4 KB
  • references/smells.md 43 KB
  • references/sources.md 5 KB
  • scripts/check_page.py 14 KB
  • scripts/heatmap.py 61 KB
  • scripts/measure.py 92 KB
  • scripts/scoping.py 21 KB

Versions

The database has no other skills named refactor-pass.

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

Downloads in the last 30 days: 0 · ranking

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

Similar skills

  • 100refactor
    Analyze complexity and smells, draft a safe refactor plan, and execute step-by-step with tests. Use when refactoring code or invoking /refactor.
  • 100refactoring
    Refactoring catalogs of Martin Fowler (Refactoring, 2nd ed.) and Joshua Kerievsky (Refactoring to Patterns): 29 code smells, 66 refactorings and 27 refactorings to patterns (Strategy, State, Command, Observer, Composite, Factory, Template Method...), each with mechanics, a C#…
  • 100refactor
    Analyzes code for smells and structural issues, proposes a safe refactoring plan, and executes it with test verification. Use when code is hard to read, maintain, or extend.
  • 100clean-code
    This skill should be used when the user asks to "refactor code", "review code quality", "apply clean code principles", "check for code smells", "improve code design", "do a clean code review", "apply SOLID principles", "fix naming", "reduce complexity", or when performing the…
  • 100code-refactoring-refactor-clean
    Refactor code with clean code principles, SOLID design patterns, and modern software engineering practices to improve quality, maintainability, and performance. Use when cleaning up or restructuring existing code.
  • 100refactoring-advisor
    Analyze code for structural issues and code smells, then recommend prioritized refactoring patterns with before/after examples. Use when the user asks to refactor, clean up, or improve code structure, when a module has grown hard to change or test, or when a review surfaces maintainability problems.

Feedback and reports

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