| name | refactor |
| description | Improve code structure without changing behavior, then create a GH Issue + PR. |
| argument-hint | [file or module path to refactor] |
| disable-model-invocation | false |
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*) |
Kit Preamble — refactor
Kit Script Root
Kit root: ${CLAUDE_PLUGIN_ROOT}
- Absolute path above → plugin install (substituted at load time; no project
scripts/ dir): prefix every kit script command with it, e.g.
bash <kit-root>/scripts/checkpoint.sh …. Absolute paths also work from worktrees.
- Literal
${…} placeholder above → standalone layout: run commands as written.
Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
[ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
[ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.
[ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.
Kit Rules
- Verify
gh auth status before any GitHub operation.
Checkpoint Rules — MANDATORY
Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. Blocking gates exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates always exit 0 and print an ADVISORY: line on failure: report the gap, self-correct, then continue (ISSUE-031). Never skip running either tier.
Slug convention: After creating the worktree, store the branch slug (e.g., refactor/extract-views-helpers) for use in checkpoint commands.
Argument Validation (run before anything else)
- If
$ARGUMENTS is empty or blank, ask the user: "Which file or directory would you like to refactor? Please provide a path."
- If a path is provided, verify it exists using Glob or Read. If the path does not exist, stop with: "Target path not found:
<path>. Please provide a valid file or directory path."
Steps:
- Ensure
gh authenticated (gh auth status).
- Read the target file or module from $ARGUMENTS.
- Read existing tests for the target to understand current behavior.
- Identify code smells (long functions, duplication, deep nesting, tight coupling, etc.).
- Present a prioritized list of proposed refactorings with rationale.
- After user approval, create worktree + auto-freeze in one step:
WT="$(bash scripts/wt_setup.sh refactor/<slug>)"
wt_setup.sh creates the worktree and writes the freeze marker inside
.claude-kit/freeze-dir.txt atomically. All subsequent file operations
happen inside $WT/.
CHECKPOINT — ADVISORY (report & continue)
Run: bash scripts/checkpoint.sh --skill refactor --phase worktree --issue "$SLUG"
Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.
- Apply refactorings one at a time inside
$WT/, running tests after each step.
- Confirm all tests pass after the final change.
CHECKPOINT — MANDATORY — NEVER SKIP
Run: bash scripts/checkpoint.sh --skill refactor --phase test --issue "$SLUG"
If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.
- Create GH Issue:
gh issue create --title "refactor: <concise description>" --body "<body>"
- Body must include: identified code smells, applied refactoring patterns, affected files, and test results.
- Commit + push (from
$WT/).
CHECKPOINT — ADVISORY (report & continue)
Run: bash scripts/checkpoint.sh --skill refactor --phase push --issue "$SLUG"
Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.
- Create PR:
gh pr create --title "refactor: <concise description>" --body "Closes #<issue_number>\n\n<details>"
- Report the PR URL to the user — continue with
/review and /ship.
Sprint Integration (optional)
If issues.md exists in the project root, register this work in the sprint ecosystem:
- Read
issues.md to find the next available ISSUE-NNN number.
- Append a new issue entry via the registry wrapper:
bash scripts/registry_edit.sh issues.md -- bash -c '<append issue entry>'
Issue fields:
- Title: same as GH Issue title
- Track: platform
- Priority: P2
- Status: done (PR already created)
- GH-Issue:
<number>
- PR:
<pr_url>
- Depends-On: none
- This allows team-lead to track standalone skill work in sprint_state.md.
If issues.md does not exist, skip this step silently.
Error Handling
- If
gh auth status fails: stop and instruct the user to run gh auth login.
- If no tests exist for the target: warn the user and suggest writing tests before refactoring.
- If tests fail after a refactoring step: revert the step and report the issue. Do NOT push or create PR.
Rollback
- Use
bash scripts/wt_cleanup.sh <branch> for safe worktree removal —
the wrapper cd's to main root and removes the worktree in a single subshell.
- If failure occurs after worktree creation but before PR:
bash scripts/wt_cleanup.sh <branch>
git push origin --delete <branch> (remote cleanup, if pushed)
- If failure occurs after PR creation:
gh pr close <pr_number> then clean up worktree and branch as above.
Shared Registry Files
IMPORTANT: Never commit issues.md, STATUS.md, or CHANGELOG.md to the feature branch.
These are registry files managed only on main. Always use bash scripts/registry_edit.sh <file> -- bash -c '<update command>' — the wrapper resolves the main repo root internally.
Guidelines
- Never change observable behavior — structure-only changes.
- Run tests after EVERY individual step — green-to-green transitions only.
- Keep each commit small and focused on one transformation.
- If test coverage is below 70% for the target code, warn the user and suggest adding tests first.
- If you discover a bug during refactoring, stop — file it as a separate issue.
- Use well-known refactoring patterns: Extract Method, Move Function, Replace Conditional with Polymorphism, Introduce Parameter Object.
Execution Principles (absorbed from the refactorer persona — ISSUE-034)
- Preserve observable behavior: if a test must change, you are rewriting, not refactoring. Add tests first where coverage is thin.
- One refactoring transformation per commit; no new abstractions "for the future" — solve today's readability/maintenance problem.
- After every step, all existing tests still pass. If you discover a bug, file it as a separate issue — do not fix it here.