Attach this capability for behavior-preserving structural cleanup of existing code. It covers clearer structure, names, boundaries, and validation that behavior is preserved. Do not attach it as the sole capability for feature work, bug fixes, unresolved source evidence, or external research; attach requirements-clarification, investigation, public-research, implementation, or epistemic-audit as needed.
Attach this capability for behavior-preserving structural cleanup of existing code. It covers clearer structure, names, boundaries, and validation that behavior is preserved. Do not attach it as the sole capability for feature work, bug fixes, unresolved source evidence, or external research; attach requirements-clarification, investigation, public-research, implementation, or epistemic-audit as needed.
Refactoring
Purpose
This capability guides behavior-preserving cleanup of existing code. Attach it to improve structure, names, boundaries, and maintainability after first understanding the current design.
When to use
the codebase structure is hard to follow
files or modules should be split, merged, or relocated
names should better reflect responsibility
duplicated logic should be consolidated
dependency direction or ownership boundaries need tightening
tests, docs, or comments need to be aligned with the refactor
When not to use
the main task is feature delivery or defect repair
the task only needs a local edit without structural impact
the request depends on external research rather than repository analysis
Refactoring evaluation criteria
Assess the change against:
behavior preservation
public API and contract stability
cohesion and coupling
responsibility clarity
naming precision
duplication reduction
complexity and readability
dependency direction
testability and change locality
removal of dead, stale, or parallel paths
Quality gates
A refactor is ready only when:
intended behavior is unchanged, or every intentional change is isolated and explained
every non-trivial diff hunk is accounted for as one of: rename, move, extraction, deletion of dead code, unchanged logic carried forward, or an explicitly intended behavior change
any newly introduced helper, API, library function, language idiom, or abstraction has its exact semantics confirmed from local usage, existing tests/docs, or an authoritative source before it replaces existing logic
touched public interfaces, schemas, configs, and entry points still line up
weak or missing coverage is backed by characterization tests or another repeatable before/after check
stale references to renamed or moved items are removed
targeted tests for affected paths pass
available static checks or linters for touched code pass
the final diff and validation checks can account for each behavior-affecting change, and any intentional behavior change is isolated and explained
Procedure
Map the current structure, call paths, and invariants.
Make a semantic inventory for the planned diff: what will be renamed, moved, extracted, deleted, or intentionally changed.
Identify the smallest coherent refactor that improves the design.
Prefer deletion, consolidation, and extraction over new abstractions.
Do not substitute existing logic with a new helper, API, library function, language idiom, or abstraction merely because it looks shorter or cleaner. If such a substitution is necessary, record the semantics evidence first; otherwise carry the existing expression forward.
Edit code, tests, docs, and prompts together when needed.
Re-read changed surfaces for stale names, duplicate paths, contradictions, and unaccounted semantic substitutions.
Validate with the most direct checks available, and include at least one before/after or characterization check when behavior preservation is not obvious from inspection.
If a behavior change is unavoidable, isolate it and treat it as a separate verified step.