code/commands/builtins/refactor.md

metadata

name: refactor
description: Refactor code for clarity, simplicity, and maintainability
argument-hint: File path or "current changes"

Refactor

Target: $ARGUMENTS

Refactor the specified code without changing its behavior.

Process

1. read_file the target.
2. Identify smells:
   • Duplicated code (extract function/component)
   • Long functions (split into smaller ones)
   • Deep nesting (early returns, guard clauses)
   • Unclear names (rename to reveal intent)
   • Magic numbers (extract constants)
   • Mixed concerns (separate responsibilities)
   • Dead code (remove)
3. Plan changes — show the user before applying if the refactor is significant.
4. Apply changes with edit_file or write_file.
5. Verify nothing broke: run tests with bash if available.

Rules

• Behavior-preserving: the refactored code must produce the same output for the same input.
• One refactor at a time: don't mix 5 changes into one edit.
• Match conventions: follow the surrounding code style.
• Update names everywhere: don't leave stale references.
• Test after each significant change.

Don't refactor for refactoring's sake. Only refactor when:

• The code is hard to read
• The code is hard to change
• The code has bugs you're about to fix anyway
• The user explicitly asked