refactoring

Assess and apply behavior-preserving code restructuring after a passing test baseline.

Updated May 18, 2024
One-click install
npx skills add https://github.com/joshhornby/dotfiles --skill refactoring-joshhornby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refactoring
Source: https://github.com/joshhornby/dotfiles/tree/main/.claude/skills/refactoring
Command: npx skills add https://github.com/joshhornby/dotfiles --skill refactoring-joshhornby

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Restructuring code without a safety net risks silently changing behavior or adding speculative complexity. This Skill enforces a disciplined refactoring workflow that keeps every change behavior-preserving, evidence-backed, and proportionate to the actual need. ## Core Features & Use Cases - Baseline Discipline: Establishes a verified, recoverable baseline after GREEN in a TDD cycle before any restructuring, with commits only on explicit user approval. - Priority Classification: Triages findings into Critical, High, Nice, and Skip categories so only worthwhile refactors are applied. - DRY and Speculation Guards: Distinguishes semantic duplication from structural similarity and blocks speculative abstractions or untested new behavior. - Use Case: After making a failing test pass, ask the assistant to assess the touched code; it extracts magic numbers, clarifies names, keeps tests green, and defers mutation testing to the pre-PR gate. ## Quick Start Ask the assistant to assess and refactor the code you just made pass its tests, keeping all behavior unchanged.

Frequently Asked Questions about refactoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor code safely without changing behavior?

Establish a passing test baseline first, then restructure in small steps while keeping focused tests green after each change. Record the baseline as a checkpoint, and only create commits with explicit approval so you can revert if something breaks.

When should I refactor during TDD?

Refactor in the REFACTOR step, immediately after GREEN establishes a passing behavior-test baseline for the increment. Skip refactoring when the current structure is not impeding the work or when the change would alter behavior.

When should I not refactor code?

Avoid refactoring when code is clean enough for the current phase, when the change would alter behavior, when it is premature optimization, or when extraction is purely for testability. Speculative generality for imagined future requirements should also be skipped.

Should I run mutation testing after every refactor?

No. Mutation testing is deferred to the pre-PR gate, where it runs once for the accumulated scope. During refactoring, keep each step small and green under the existing tests, since the baseline is not yet mutation-verified.

How do I decide whether to extract duplicated code?

Abstract only when the duplication represents the same business concept that would change together with requirement changes. Keep structurally similar but semantically different code separate, since coupling unrelated concepts creates confusion.