From 1bc7711f38d72c886f28facab1eca6fd7a48592b Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Sat, 25 Jul 2026 18:25:03 +0200 Subject: [PATCH] feat(refactor): add skill for cleaning up the uncommitted change set The skill refactors every file that is currently uncommitted in the git working tree up to the project's coding standards, without changing behaviour and without widening the scope to untouched files. Co-Authored-By: Claude Opus 5 (1M context) --- skills/refactor/SKILL.md | 68 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 skills/refactor/SKILL.md diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md new file mode 100644 index 0000000..ec1f105 --- /dev/null +++ b/skills/refactor/SKILL.md @@ -0,0 +1,68 @@ +--- +name: refactor +description: > + Refactor every file that is currently uncommitted in the git working tree - + staged, unstaged and untracked - up to the project's coding standards, + without changing behaviour. Trigger on /refactor or when the operator asks to + clean up, tidy, or polish the current changes before committing. Portable + across projects. +--- + +The unit of work is the uncommitted change set, not the repository. Behaviour +stays identical: a refactor that changes what the code does is a bug, not a +cleanup. + +## Step 1: fix the file set + +Read the set from git, never from memory of what was edited: + +```bash +git status --porcelain +``` + +Take modified, added, renamed and untracked files. Drop deleted files, binaries, +lockfiles, vendored trees and generated output. Restate the resulting list in +one line before touching anything; if it is empty, say so and stop. + +Never `git stash` and never revert a working-tree file to compare - other agents +and the operator share this tree. Read the committed version with +`git show HEAD:` into a temporary file instead. + +## Step 2: refactor each file + +Read the whole file first, then apply the standards that the surrounding code +and the project's own config already establish (formatter config, linter rules, +existing idioms) over any generic preference of your own: + +- **Duplication**: fold repeated logic into the helper that already exists; + create a new one only when two or more call sites need it now. +- **Dead weight**: unused imports, variables, parameters, branches that cannot + be reached, flags with a single value, abstractions with one implementation. +- **Naming**: names that state what a thing is, matching the file's convention. +- **Shape**: split a function that needs a scroll to read; collapse nesting by + returning early; replace magic values with a named constant at its use site. +- **Errors**: never widen a caught exception, never swallow one, never remove a + validation or a security check to make the code shorter. +- **Comments**: invoke the `comments-clean` skill rather than reimplementing its + rules here. + +Do not reformat regions you have no substantive fix for - cosmetic churn buries +the real change in the diff. If a file's problem is architectural and cannot be +fixed inside the change set, report it instead of half-doing it. + +## Step 3: keep behaviour provable + +- Never fold a bug fix, a feature, or a dependency change into a refactor. + Found a real bug? Name it in the report and leave it for a separate change. +- Run the cheap checks the project already has for the touched files (formatter, + linter, the module's own unit tests). Do not start a full suite, a build, or a + deploy on your own initiative - propose it and let the operator trigger it. +- State plainly what was verified and what was not. An unverified refactor is + reported as unverified. + +## Step 4: report + +One line per file: what changed and why it is safe. Then one line naming what +was deliberately left alone (architectural findings, bugs, files skipped) and +the exact command the operator can run to validate. Do not commit unless the +operator asked for a commit.