refactor

Refactoring agent

When to use

• Rule of Three: Third instance triggers extraction. Exception: security and validation logic warrants unification at 2+.
• Adding features: Restructure to accommodate the change first.
• Fixing bugs: Clarify structure to expose the error.
• Code review: Improve unfamiliar code incrementally.
• Smells detected: See violation catalog in references/refactoring-guide.md.

Goal

• Execute disciplined, semantics-preserving transformations to remove DRY, SOLID, and Structure violations, improving maintainability without altering observable behavior.

Input

Determine scope by the first available source:

• Files or folders provided by the user.
• Current changes in the repository.

Abort if no scope exists.

Current changes: staged and unstaged edits, deletions, and renames of tracked files, plus new untracked files. Requires a versioned project. Abort with a clear message if none detected.

Testing

See references/testing-guide.md for test structure, isolation, mocking, assertion, and performance standards.

Shell commands

See references/shell-command-guide.md for command safety, timeouts, redirects, and non-interactive environment directives.

Cleanup

See references/cleanup-guide.md for the self-introduced-artifact checklist and diff-only audit scope.

Workflow

1. GATE—Precondition guard. Halt immediately on failure.
   • Abort if no scope exists.
   • Read references/testing-guide.md.
   • Read references/shell-command-guide.md.
   • Read references/cleanup-guide.md.
   • Read relevant production code, adjacent tests, and test commands.
   • Confirm automated test suite passes before touching code.
   • Detect antipatterns using the violation catalog in references/refactoring-guide.md.
   • Short-circuit: halt and emit Result: No Changes if none detected: duplicated logic, long methods, large classes, primitive obsession, SOLID violations.
2. ORIENT—Name the smallest production area worth refactoring and what won't change.
3. PLAN—Declare the minimal change and rationale.
   • Analyze package, module, or class boundaries for cyclic imports and unresolved downstream consumers.
   • Select the fix from the playbook; resolve compound violations using the triage rules in references/refactoring-guide.md.
4. ACT—Apply one transformation at a time. Execute only what PLAN declared.
5. VERIFY—Loop over every criterion declared in PLAN:
   • Run the full suite after each ACT step.
   • Audit the task's own git diff/git status against the Self-cleanup checklist in references/cleanup-guide.md; remove every self-introduced artifact before proceeding.
   • For each unmet criterion: backtrack to last known-good state, return to ACT, and re-enter VERIFY.
   • Exit only when all criteria pass.
   • Halt only for out-of-scope blockers.
6. REPORT—Emit the result following the result directives and using the result template.