From lattice
Restructures existing code safely without changing external behavior. Uses context, design, architecture, and testing guardrails in a characterization-first workflow.
How this skill is triggered — by the user, by Claude, or both
Slash command
/lattice:refactor-safelyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Load these skills based on refactor scope (see Steps 3, 5, 6 for conditional use):
Load these skills based on refactor scope (see Steps 3, 5, 6 for conditional use):
framework:knowledge-priming -- Load project context (always)framework:context-anchoring -- Load/capture context doc (always)framework:learning-harvest -- Load prior learnings; harvest at session end (always)framework:collaborative-judgment -- Surface trade-offs in structure, seams, migration sequence (always)framework:clean-code -- Readability, responsibility boundaries, local craft (always)framework:test-quality -- Characterization tests and safety net (always)framework:design-first -- Significant structural changes (conditional)framework:architecture -- Layer placement and dependency direction (conditional)framework:domain-driven-design -- Aggregate boundaries and domain behavior (conditional)framework:secure-coding -- Security-sensitive code (conditional)Start from current pain, not preferred abstraction.
framework:learning-harvest Load behavior. Focus hint: "refactoring session — focus: structural health, quality signals".framework:context-anchoring Document Discovery to check for existing context doc for affected feature/module
End step, summarize intent one sentence:
"Refactor X to improve Y while preserving Z."
STOP: If can't state improvement target and preservation target that clearly, continue clarifying before planning changes.
Optional persistence check:
framework:context-anchoring, then use as source of truth for approved planRefactoring changes structure, not behavior. Make preservation contract explicit before proposing structural edits.
List behaviors that must remain unchanged:
Also list explicit out-of-scope changes:
This step defines refactor's safety boundary. If desired outcome requires changing preserved behavior, stop and discuss whether task actually bug fix, feature, or broader redesign.
Zero Refactor Rule: no structural code changes until user approves target structure and transition plan.
For small refactors, plan may be brief. For larger ones, use framework:design-first selectively:
Present:
End step with explicit gate:
"Does this refactor plan look correct? Should I proceed to Step 4: characterization tests?"
STOP: Don't write refactor code until user explicitly approves.
If persistence enabled, use framework:context-anchoring Enrich behavior to capture approved preservation boundaries, target structure, movement plan, out-of-scope items. STOP: Don't proceed to Step 4 until plan written.
Before changing structure, lock current behavior with tests.
framework:test-quality inlineStopping rule:
End step with explicit gate:
"Characterization tests in place and passing. Ready to discuss refactor strategy and pacing?"
STOP: Don't proceed to strategy selection until safety net verified green.
After user approves high-level plan and safety net in place, choose implementation approach.
Preferred strategies:
framework:architecturePreferred pacing:
"How would you like review refactor?"
- Slice-by-slice (recommended) -- Refactor one safe slice at time, pause after each slice. Best for risky legacy code.
- Layer-by-layer -- Complete refactor for one structural layer or concern, then pause for review. Best for broader architectural cleanup.
- Full autonomy -- Execute approved refactor end-to-end, present complete result at end. Best for tightly scoped, low-risk refactors. (Still pause if slice reveals approved plan unsafe or invalid — see Step 6 Deviation Rule.)
Default to slice-by-slice if user doesn't express preference.
Implement only within approved preservation boundaries and target structure.
For each slice:
framework:collaborative-judgment, surface them before presenting slice's code. Don't interrupt mid-slice unless approved plan becomes unsafe or invalid.Always apply:
framework:clean-code -- better boundaries, simpler control flow, smaller focused units, clearer namingframework:test-quality -- maintain strong characterization tests and nearby supporting testsConditionally apply:
framework:architectureframework:domain-driven-designframework:secure-codingDeviation rule:
Refactor succeeds only if both true:
Verify preservation:
Verify structural improvement:
When reporting completion, be explicit about both:
Use framework:context-anchoring Enrich behavior to preserve important parts of refactor:
If no context doc exists and refactor involved non-trivial structural reasoning, suggest creating one so decisions not lost across sessions.
Use framework:learning-harvest Harvest behavior. Session context: "refactoring session — structural restructuring and debt resolution". Synthesize and propose cross-cutting patterns from this session — structural debt that accumulated, migration strategies that worked, characterization test gaps discovered. User confirms what enters the document.
After refactor complete, recommend /review when change:
npx claudepluginhub techygarg/lattice --plugin latticeInternal code quality improvement workflow that restructures code and simplifies modules without changing external behavior. Use when refactoring to improve maintainability.
Orchestrates behavior-preserving refactors: confirm tests green, restructure in small steps, keep tests green, review, and gated commit. Use when structure should improve but behavior must not change.
Safely refactors code test-first: verifies/writes tests, one structural change at a time, preserves behavior. Use for 'refactor this', 'clean this up', reorganization.