refactor
Skill8 starsChanged 35 days agoMITView on GitHub
Refactor existing code with impact analysis first. Routes to tech-lead for blast-radius assessment, then engineers, with heavy emphasis on test coverage. Use when restructuring code with no intended behavior change. Trigger this when someone says: refactor this, clean up this code, extract this pattern, restructure this, this code is messy, improve the code structure, rename this across the codebase, remove duplication. Do NOT use when the change modifies behavior — use /implement instead. Do NOT use for single-file cleanup — just edit the file directly.
195 other projects use a version of this.
Adopted by
Most recently taken up by
- erikperttu/steering-coding-agentstheir own version, first seen Nov 16, 2026
- Archont561/skillstheir own version, first seen Nov 15, 2026
- nazmirket/skillstheir own version, first seen Nov 15, 2026
- qivora-labs/agentinittheir own version, first seen Nov 15, 2026
- NomadicDaddy/aiddtheir own version, first seen Nov 15, 2026
- zircote-plugins/refactortheir own version, first seen Nov 15, 2026
Used with
Projects with it also use ascii-diagram, debug-fix and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SethGammonSkillascii-diagram
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
Also in 4 projects that use this
zebbernSkilldebug-fix
Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)
Also in 4 projects that use this
parcadeiSkillagent-context-isolation
Agent Context Isolation
Also in 3 projects that use this
parcadeiSkillagentica-infrastructure
Reference guide for Agentica multi-agent infrastructure APIs
Also in 3 projects that use this
- +8 more from parcadei
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- github/awesome-copilot★ 41ksame name
- unkeyed/unkey★ 5.5ksame name
- parcadei/Continuous-Claude★ 3.9ksame name
- parcadei/Continuous-Claude-v2★ 3.9ksame name
- parcadei/Continuous-Claude-v3★ 3.9ksame name
- adobe/S3Mock★ 1.2ksame name
- SethGammon/Citadel★ 927same name
- poshan0126/dotclaude★ 871same name
- JordanCoin/codemap★ 715same name
- membrane/api-gateway★ 658same name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- backlogSkill
- conventionsSkill
- debugSkill
- devops-azureSkill
- devops-githubSkill
- devopsSkill
- hotfixSkill
- implementSkill
- interview-meSkill
- lint-agentsSkill
- memory-auditSkill
- memory-querySkill
- obsidian-briefSkill
- obsidian-captureSkill
- obsidian-dailySkill
- obsidian-recapSkill
- obsidian-searchSkill
- obsidianSkill
- onboardSkill
- pack-reviewSkill
- planSkill
- repo-mapSkill
- review-prSkill
- scaffoldSkill
- setup-projectSkill
- smellSkill
- spec-intakeSkill
- system-checkSkill
- whatSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 12 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 170 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Always first. Confirm the working branch.
- Distinctive: line 25
Always invoke tech-lead before any engineer for a refactor.
- Very specific: line 52
Check $env:OBSIDIAN_VAULT_PATH.
- Very specific: line 62
If obsidian-writer errors or the vault directory is missing, continue — the project's memory/ file is the authoritative record.
- Distinctive: line 78
If ancestry fails (non-zero exit), the worktree is stale — it started from main, not the refactor branch, and its diff may be missing …
- Distinctive: line 86
If the patch does not apply cleanly, stop and route back to the engineer with the conflicting file list rather than resolving it yourself.
- Distinctive: line 93
Run ts-linter immediately after frontend-engineer or mcp-engineer.
- Distinctive: line 99
Run security-reviewer and performance-reviewer only if the refactor touches auth, data access, or hot-path code.
- Distinctive: line 103
After code-reviewer. Focus on:
- Distinctive: line 120
If PASS: push and optionally open a PR.
- Distinctive: line 121
If FAIL: retry up to 2 cycles.
- Distinctive: line 126
Pre-existing failing tests: Run the test suite before the refactor begins (step 1 or before step 5).
- Distinctive: line 128
Behavior change masquerading as refactor: If the user's request includes any change to output format, API response shape, error messages, …
- Distinctive: line 129
Test coverage decrease is a blocker: If test-engineer finds that the refactor reduced meaningful coverage (not just line count), route back …
“Common” is measured: kept by at least 6 in 10 of the 170 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Refactor
Restructure existing code without changing observable behavior. The defining constraint: no behavior delta — all existing tests must still pass after the refactor.
1. Define the refactor
Confirm with the user:
- What is being refactored (files, modules, or patterns)
- Why (readability, performance, removing duplication, preparing for a future change)
- What must not change (public API surface, database behavior, external contracts)
Read docs/CONVENTIONS.md if it exists. Check memory/**/*.md for any decisions about the code being changed. If memory/architecture/repo-map.md exists, use it to scope the blast radius quickly — it maps which directories own what. Verify its verified-at-commit against HEAD; if the structure has drifted, recommend /repo-map refresh before the impact analysis in step 3.
2. git-engineer — branch setup
Always first. Confirm the working branch. If on main or master, ask the user to name the refactor branch before proceeding.
3. tech-lead — impact analysis
Always invoke tech-lead before any engineer for a refactor. Pass:
- The refactor scope and goal
- The "must not change" constraints from step 1
The tech-lead will:
- Identify all files and call sites affected by the change
- Flag whether any public API surface, interface, or contract is at risk
- Determine whether the change is safe to parallelize or must be sequential
- Produce a sequenced plan
Present the plan to the user. If the tech-lead flags the refactor as high-blast-radius or pattern-changing, or if the plan introduces a new pattern (even one extracted from existing code), recommend running devils-advocate on the plan before proceeding.
4. devils-advocate (conditional)
Invoke if tech-lead flags the refactor as:
- Touching more than 5 files across layers
- Changing a shared abstraction used in many places
- Introducing a new pattern that did not exist before
Skip for straightforward extractions, renames, or formatting changes.
4a. Obsidian sync requests
tech-lead (step 3) and devils-advocate (step 4) write memory files but cannot reach the
vault themselves — neither grants Bash or Agent. When either one ends its output with
an ## Obsidian sync request section, you own the dispatch:
- Check
$env:OBSIDIAN_VAULT_PATH. If empty, skip silently — do not tell the user. - For each memory file listed in that section, dispatch obsidian-writer with:
write_mode:"capture"vault_path:OBSIDIAN_VAULT_PATHprojects_folder:OBSIDIAN_PROJECTS_FOLDER(empty string if unset)project: basename of the project directorytitle: the description given on that file's linebody: full content of the memory file (frontmatter + body)timestamp: current datetime inYYYY-MM-DDThh:mmformat
If obsidian-writer errors or the vault directory is missing, continue — the project's
memory/ file is the authoritative record. Never block the refactor on a failed sync.
5. Engineer agents
Dispatch based on file types, following the plan from tech-lead. Use isolation: "worktree" for each engineer. Worktrees only branch from the current refactor branch's HEAD if worktree.baseRef is "head" in settings.json — if unset or "fresh", the harness silently bases new worktrees on local/origin main instead. Collect both the worktree path and branch name returned by each agent for cleanup after merge-reviewer.
Immediately after each engineer returns, verify the worktree actually branched from the refactor branch:
git merge-base --is-ancestor <refactor-branch> <worktree-branch> # correct base?
git log --oneline <refactor-branch>..<worktree-branch> # any commits at all?An empty commit list is also a failure, even when ancestry passes. Engineers are told not to commit — merge-reviewer owns commits — so a worktree branch routinely has zero commits while the work sits uncommitted. merge-base --is-ancestor is trivially satisfied then, so this check passes and merge-reviewer's later git merge --no-ff merges nothing while reporting success, silently stranding the work. If the commit list is empty, check git -C <worktree-path> status --short: modifications mean use the repair recipe below (it captures uncommitted changes by design); a clean worktree means the engineer changed nothing, which is a finding in its own right.
If ancestry fails (non-zero exit), the worktree is stale — it started from main, not the refactor branch, and its diff may be missing refactor-branch-only changes. Repair before continuing:
git -C <worktree-path> diff "$(git -C <worktree-path> merge-base main HEAD)" > /tmp/<worktree-branch>.patch
git -C <worktree-path> reset --hard <refactor-branch>
git -C <worktree-path> apply --3way /tmp/<worktree-branch>.patchIf the patch does not apply cleanly, stop and route back to the engineer with the conflicting file list rather than resolving it yourself.
Pass each engineer:
- The refactor goal and constraints
- The specific files they own
- A reminder: no behavior delta — existing tests must pass
Run ts-linter immediately after frontend-engineer or mcp-engineer. Block on FAIL.
6. code-reviewer
Invoke with the explicit note that this is a refactor — reviewer should flag any unintended behavior changes, not just style issues.
Run security-reviewer and performance-reviewer only if the refactor touches auth, data access, or hot-path code. State your reasoning.
7. test-engineer
After code-reviewer. Focus on:
- Any new abstractions or extracted functions that lack direct test coverage
- Ensuring the refactor did not reduce meaningful coverage
8. merge-reviewer
No plan governs a refactor run, deliberately — and this one is worth understanding. This skill passes no
plan_id, so merge-reviewer's gate 4a reports "not applicable". Note that step 3 always invokes tech-lead, so a planner does run here — but it is dispatched for blast-radius analysis, not instructed to write a plan file, and tech-lead writes one only when told to. That is deliberate: if tech-lead wrote a plan unconditionally, every refactor would acquire acceptance bars and a gate enforcing them, and this skill's steps say nothing about producing or maintaining either. Do not instruct tech-lead to write a plan here without also deciding who fills## Deviationsand who answers for the bars.
Final gate. Pass the worktree branch names and a summary of all stages. merge-reviewer will merge worktree branches into the refactor branch, clean up worktrees and temporary branches, then run the gate checklist.
If PASS: push and optionally open a PR. Note in the PR description that this is a pure refactor with no behavior change. If FAIL: retry up to 2 cycles. New worktrees on retry are also created from the refactor branch. Collect new paths/branches and pass them to the next merge-reviewer invocation.
Gotchas
- Refactor that discovers a bug: If an engineer finds a bug while refactoring, do not fix it in the same PR. Note it, complete the refactor with no behavior change, and create a separate /debug or /implement task for the bug. Mixing bug fixes into a refactor obscures the change history and breaks the "no behavior delta" guarantee.
- Pre-existing failing tests: Run the test suite before the refactor begins (step 1 or before step 5). If tests were already failing before your changes, document that baseline. Do not accept responsibility for pre-existing failures, but do not hide them either.
- The devils-advocate threshold is a guideline: The "5+ files" and "shared abstraction" conditions are signals, not rules. Use judgment. A 2-file refactor that changes a foundational interface used everywhere warrants devils-advocate. A 10-file rename of a private module probably does not.
- Behavior change masquerading as refactor: If the user's request includes any change to output format, API response shape, error messages, or business logic — even a "minor cleanup" — it is not a pure refactor. Use /implement instead and make the behavior change explicit.
- Test coverage decrease is a blocker: If test-engineer finds that the refactor reduced meaningful coverage (not just line count), route back to the engineer before merge-reviewer. A refactor that deletes test coverage is not complete.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

