refactor · diff
git:20260527.8152be1 to git:20260630.95d2bc8
31 added, 74 removed. Audit A to A.
---
name: refactor
description: >-
- Refactors code to improve readability, reduce complexity, and enhance maintainability
- without altering functionality. Use when the user says "refactor", "simplify this
- code", "clean up", "reduce complexity", "extract method", "this is too complex", or
- asks to improve naming/structure without changing behavior. Preserves all public APIs
- unless explicitly authorized.
+ Performs behavior-preserving refactors to improve readability, reduce
+ complexity, and enhance maintainability without altering functionality. Use
+ when the user says "refactor", "simplify this code", "clean up", "reduce
+ complexity", "extract method", "this is too complex", or asks to improve
+ naming/structure without changing behavior. Preserves all public APIs unless
+ explicitly authorized.
---
# Refactor
- You are a refactoring specialist. Your core principle: improve code quality without
- changing externally observable behavior or public APIs — unless explicitly authorized.
+ Behavior-preserving refactor: improve code quality without changing externally
+ observable behavior or public APIs unless explicitly authorized.
## Methodology
- ### Step 1 — Analyze Before Acting
-
- Read the code fully. Identify its public interfaces and map its current behavior.
- Never assume — verify your understanding. Identify the specific problem:
- complexity? duplication? naming? coupling?
+ ### Step 1 — Characterize Current Behavior
- ### Step 2 — Preserve Behavior
+ Done when public interfaces, side effects, error behavior, performance
+ assumptions, and available tests or characterization checks are listed. If
+ behavior is ambiguous and untested, pause with the ambiguity instead of
+ rewriting.
- Your refactorings must maintain:
- - All public method signatures and return types
- - External API contracts
- - Side effects and their ordering
- - Error handling behavior
- - Performance characteristics (unless explicitly improving them)
+ ### Step 2 — Identify the Refactor Target
- Tests must still pass after every refactoring. If tests don't exist, flag this before
- proceeding — refactoring without tests is rewriting.
+ Read the code fully and name the specific problem: complexity, duplication,
+ naming, coupling, dead code, unclear data structure, or control flow. Done only
+ when the intended improvement can be checked after the change.
### Step 3 — Apply Simplification Techniques (in priority order)
1. **Reduce Complexity** — simplify nested conditionals, use early returns
2. **Eliminate Redundancy** — remove duplicate code, apply DRY principles
3. **Improve Naming** — descriptive names that reveal intent
4. **Extract Methods** — break large functions into smaller, focused ones
5. **Simplify Data Structures** — use appropriate collections and types
6. **Remove Dead Code** — eliminate unreachable or unused code
7. **Clarify Logic Flow** — make the happy path obvious, handle edge cases clearly
### Step 4 — Quality Checks Per Refactoring
For each change:
- - Verify the change preserves behavior
- - Confirm tests still pass (note if tests need updates)
+ - Verify behavior is preserved with tests or characterization notes
+ - Confirm tests still pass, or report why they could not be run
- Check that complexity genuinely decreased
- Confirm the code is more readable than before
### Step 5 — Communication Protocol
- Explain each refactoring and its benefit
- - Highlight any risks or assumptions made
+ - Highlight risks or assumptions
- Provide before/after comparisons for significant changes
- - Note patterns or anti-patterns observed
- If a public API change would significantly improve the code, ask for permission first
### Step 6 — Constraints and Boundaries
- Never change public APIs without explicit permission
- - Maintain backward compatibility
- - Preserve all documented behavior
+ - Maintain backward compatibility and documented behavior
- Don't introduce new dependencies without discussion
- Respect existing code style and conventions
- - Keep performance neutral or better
+ - Keep performance neutral or better unless explicitly improving it
- One concern per refactor — don't mix renaming, extraction, and logic changes
### Step 7 — When to Seek Clarification
Pause and ask when:
- Behavior is ambiguous and no tests document it
- - Potential bugs that refactoring would expose
+ - A potential bug would be exposed or fixed by the refactor
- A public API change would greatly simplify the code
- Performance trade-offs exist
- Architectural decisions affect the refactoring approach
- ## Common Patterns
-
- **Extract when intent is unclear:**
- ```typescript
- // Before — what does this do?
- const result = items.filter(i => i.status === 'active' && i.createdAt > cutoff);
-
- // After — intent is obvious
- const recentActiveItems = items.filter(isRecentAndActive);
- ```
-
- **Simplify conditionals:**
- ```typescript
- // Before
- if (user !== null && user !== undefined && user.role === 'admin') { ... }
-
- // After
- if (user?.role === 'admin') { ... }
- ```
-
- **Replace magic values:**
- ```typescript
- // Before
- if (retries > 3) { ... }
-
- // After
- const MAX_RETRIES = 3;
- if (retries > MAX_RETRIES) { ... }
- ```
+ ## Completion Gate
- **Flatten nesting** — early returns reduce indent depth:
- ```typescript
- // Before
- function process(data) {
- if (data) {
- if (data.valid) {
- return transform(data);
- }
- }
- }
+ Do not call a refactor complete until:
- // After
- function process(data) {
- if (!data?.valid) return;
- return transform(data);
- }
- ```
+ - behavior characterization is documented
+ - tests or characterization checks were run, or the gap is explicitly reported
+ - public API compatibility is confirmed
+ - before/after complexity or readability improvement is stated
+ - any behavior changes are separated and approved as non-refactor work
## Output Format
Every refactoring response includes:
- The refactored code
- Summary of changes made and why each improves the code
+ - Evidence that behavior was preserved
- Any caveats or areas requiring attention
- Suggestions for further improvements if applicable
## Anti-Patterns to Avoid
- Abstracting things that are only similar on the surface
- Adding layers of indirection that make code harder to follow
- Renaming without a clear semantic improvement
- Refactoring code you don't fully understand yet
- Mixing refactoring with bug fixes or feature additions in the same commit