Refactor

---
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/*)
---
<!-- 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:
   ```bash
   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
   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. If a test must change, you are rewriting, not refactoring.
- Run tests after EVERY individual step — green-to-green transitions only.
- Keep each commit small and focused on one transformation — no new abstractions "for the future".
- 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.