Refactor

<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

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)

1. If $ARGUMENTS is empty or blank, ask the user: "Which file or directory would you like to refactor? Please provide a path."
2. 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:

1. Ensure gh authenticated (gh auth status).
2. Read the target file or module from $ARGUMENTS.
3. Read existing tests for the target to understand current behavior.
4. Identify code smells (long functions, duplication, deep nesting, tight coupling, etc.).
5. Present a prioritized list of proposed refactorings with rationale.
6. 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.

7. Apply refactorings one at a time inside $WT/, running tests after each step.
8. 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.

9. 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.
10. 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.

11. Create PR:
    • gh pr create --title "refactor: <concise description>" --body "Closes #<issue_number>\n\n<details>"
12. 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:

1. Read issues.md to find the next available ISSUE-NNN number.
2. 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
3. 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:
  1. bash scripts/wt_cleanup.sh <branch>
  2. 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.