← Back to Small task
See how it helps
Refactoring value review
Evaluates whether restructuring removes a real obstacle to current work and keeps justified cleanup separate from speculative churn.
refactoring-value-review
Workflow agents using this skill
When is it useful?
Use it when a feature proposal includes refactoring whose immediate benefit or scope is unclear.
What does it help you do?
- Links cleanup to an active change or verified recurring defect.
- Separates restructuring from behavioral modifications.
- Rejects speculative abstractions that couple unrelated domain concepts.
Try asking this
Assess whether extracting this shared helper actually simplifies our current feature. Compare the helper's callers and reasons to change. Keep the extraction only if it removes a current maintenance problem without coupling unrelated business rules.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
Show less
Refactoring Value Review
Use this skill when evaluating proposed refactorings — either standalone or embedded inside a feature/bugfix plan — to ensure structural changes pay for themselves right now rather than creating unrequested churn and regression risk.
Kent Beck's Rule vs. Speculative Churn
- High-value preparatory refactoring: "Make the change easy (warning: this may be hard), then make the easy change." A focused refactoring that directly removes friction for the current accepted task or eliminates a verified recurring bug source is well-justified.
- Low-value speculative refactoring: Reorganizing folders, renaming stable internal APIs, converting working modules to a new pattern, or abstracting code that nobody is currently modifying "just to clean up technical debt" wastes budget and muddies diffs.
Workflow
- Ask the three refactoring value questions:
- What current change or verified defect does this unlock? If the answer is "none right now, it just looks cleaner", defer it out of the current work item.
- Does it genuinely reduce system complexity (Ousterhout)? Does it shrink interfaces, eliminate duplicated state invariants, or remove a pass-through layer? Or does it merely shuffle code across more files and indirections?
- What is the regression blast radius? Does the touched code have deterministic test coverage to prove behavior is preserved?
- Keep refactoring commits / steps isolated from behavior changes:
- Never mix a 30-file structural rename or extraction into the same step as a subtle business-logic change or security fix.
- If a small local preparatory refactor is needed, keep it narrowly scoped to the exact module being modified.
- Distinguish toxic debt from quiet legacy code:
- Fix now: Duplicated business rules that drift out of sync, missing tenant/permission guards at a service boundary, or tangled state that causes active bugs in the area being changed.
- Leave alone: Stable, rarely touched modules that work reliably even if written in an older style.
Anti-Patterns to Avoid
- The "While I'm Here" cascade: Touching 5 unrelated subsystems during a small bugfix, multiplying review burden and merge conflicts.
- Abstraction for DRY's sake alone (Sandimetz / Rule of Three): Coupling two distinct domain concepts into a single parameterized helper with 6 boolean flags is worse than two clear, separate 15-line functions.
Included files 1
SKILL.md