# Refactor

> Guided refactoring with before/after validation Use when this capability is needed.

- Skill: `tomevault-io/refactor-14` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/refactor-14`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/refactor-14/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/refactor-14

---


Perform a guided refactoring of the specified code with validation at each step.

## Scope

- If `$ARGUMENTS` is a file: refactor that specific file.
- If `$ARGUMENTS` is a module/directory: analyze and refactor across the module.
- If `$ARGUMENTS` is empty: analyze recently changed files (`git diff --name-only main...HEAD`).

## Workflow

### 1. Analyze
- Read the target code and identify refactoring opportunities.
- Categorize: extract function, rename, simplify conditional, reduce duplication, improve types, restructure module.
- Estimate risk level for each change (low/medium/high).

### 2. Baseline
- Run `make test` (or appropriate test command) to establish a passing baseline.
- If tests fail before refactoring, stop and report — don't refactor broken code.
- Record the baseline state: `git stash` or note current diff.

### 3. Plan
Present the refactoring plan to the user:

```
## Refactoring Plan: <target>

| # | Change | Risk | Files |
|---|--------|------|-------|
| 1 | Description | low | file.py:20-35 |
| 2 | Description | medium | file.py:50-80 |

Estimated complexity reduction: X → Y (metric)
```

Wait for approval before proceeding.

### 4. Apply
- Apply changes **one at a time**, smallest and safest first.
- After each change: run tests immediately.
- If tests fail: revert that change, report the failure, and continue with remaining changes.
- Never apply the next change until the current one passes tests.

### 5. Report
Write results to `scratch/refactor_latest.md`:

```
## Refactoring Report: <target>

### Applied
- [x] Change 1 — description (tests pass)
- [x] Change 2 — description (tests pass)

### Skipped
- [ ] Change 3 — reason (tests failed / user declined)

### Before/After
- Lines: X → Y
- Complexity: before → after
- Tests: all passing
```

Return a ≤5 line summary to the main context.

## Rules

- **Never break tests.** If a change causes failures, revert it immediately.
- **One change at a time.** Don't batch multiple refactors into one edit.
- **Preserve behavior.** Refactoring changes structure, not functionality.
- **No scope creep.** Don't add features, fix bugs, or change behavior during refactoring.
- **Ask before high-risk changes.** Anything touching public APIs, shared interfaces, or core logic needs explicit approval.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/sakebomb) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->