refactor-safely

Name: refactor-safely
Author: techygarg

165stars12forks

How to install refactor-safely?

techygarg/lattice/refactor-safely

$npx -y skills add techygarg/lattice --skill refactor-safely

Installs into the current project.

Summary

Restructure existing code safely without changing externally observable behavior. Composes context, design, architecture, code quality, and testing guardrails into a characterization-first refactoring workflow. Use when the user says 'refactor this', 'clean this up', 'untangle th

Files · 1

View on GitHub

SKILL.md

1	# Refactor Safely
2
3	## Required Skills
4
5	Load these skills based on refactor scope (see Steps 3, 5, 6 for conditional use):
6
7	1. `framework:knowledge-priming` -- Load project context (always)
8	2. `framework:context-anchoring` -- Load/capture context doc (always)
9	3. `framework:learning-harvest` -- Load prior learnings; harvest at session end (always)
10	4. `framework:collaborative-judgment` -- Surface trade-offs in structure, seams, migration sequence (always)
11	5. `framework:clean-code` -- Readability, responsibility boundaries, local craft (always)
12	6. `framework:test-quality` -- Characterization tests and safety net (always)
13	7. `framework:design-first` -- Significant structural changes (conditional)
14	8. `framework:architecture` -- Layer placement and dependency direction (conditional)
15	9. `framework:domain-driven-design` -- Aggregate boundaries and domain behavior (conditional)
16	10. `framework:secure-coding` -- Security-sensitive code (conditional)
17
18	## Workflow
19
20	### Step 1: Establish Refactor Context
21
22	Start from current pain, not preferred abstraction.
23
24	- Identify target area: module, service, aggregate, endpoint path, subsystem
25	- Clarify why refactor needed: mixed responsibilities, duplication, wrong-layer logic, coupling, poor testability, unreadable control flow
26	- Clarify what user expects to improve: simpler structure, correct layer placement, smaller units, clearer domain behavior, easier testing, safer extension points
27	- Use `framework:learning-harvest` Load behavior. Focus hint: "refactoring session — focus: structural health, quality signals".
28	- Use `framework:context-anchoring` Document Discovery to check for existing context doc for affected feature/module
29	- If found → Load it (context-anchoring Load behavior). Honor existing decisions and constraints as active commitments while planning refactor
30	- If not found → Proceed from conversation and current code. Don't block planning on missing context
31
32	End step, summarize intent one sentence:
33
34	> "Refactor X to improve Y while preserving Z."
35
36	STOP: If can't state improvement target and preservation target that clearly, continue clarifying before planning changes.
37
38	Optional persistence check:
39
40	- If refactor substantial, risky, or likely span multiple sessions, ask whether user wants persist approved plan
41	- If relevant context doc already exists and user wants persistence → load and update it
42	- If no relevant doc exists and user wants persistence → propose creating one, confirm doc name per `framework:context-anchoring`, then use as source of truth for approved plan
43	- If user doesn't want persistence or refactor small and local → continue in non-persistent mode. Approval gates still apply; plan simply remains in-session
44
45	### Step 2: Define Preservation Boundaries
46
47	Refactoring changes structure, not behavior. Make preservation contract explicit before proposing structural edits.
48
49	List behaviors that must remain unchanged:
50
51	- Public API contracts and response shapes
52	- Domain invariants and state transitions
53	- Persistence semantics and side effects
54	- Event emission and integration behavior
55	- Authorization and security posture
56	- Error behavior where externally visible
57	- Performance or operational characteristics if part of current contract
58
59	Also list explicit out-of-scope changes:
60
61	- New features
62	- Schema changes
63	- Contract changes
64	- Intentional behavior changes
65	- Unrelated cleanup outside approved area
66
67	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.
68
69	### Step 3: Propose High-Level Structural Plan
70
71	Zero Refactor Rule: no structural code changes until user approves target structure and transition plan.
72
73	For small refactors, plan may be brief. For larger ones, use `framework:design-first` selectively:
74
75	- Start at Level 2 (Components) to define target responsibilities and boundaries
76	- Use Level 3 (Interactions) when data flow or dependency direction will change
77	- Use Level 4 (Contracts) when internal interfaces or seams need formalized
78	- Don't use Level 1 (Capabilities) unless user-facing scope actually changing
79
80	Present:
81
82	- Current structural problems -- what wrong with current shape
83	- Target structure -- what components, classes, functions should exist after refactor
84	- Movement plan -- what logic moves where
85	- Preservation boundaries -- what will stay behaviorally unchanged
86	- Out-of-scope items -- what will not be changed this pass
87
88	End step with explicit ga

People who liked this also viewed

6 picks

Type

refactor-safely

165stars12forks

View on GitHub

How to install refactor-safely?

techygarg/lattice/refactor-safely

$npx -y skills add techygarg/lattice --skill refactor-safely

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Refactor Safely
2
3	## Required Skills
4
5	Load these skills based on refactor scope (see Steps 3, 5, 6 for conditional use):
6
7	1. `framework:knowledge-priming` -- Load project context (always)
8	2. `framework:context-anchoring` -- Load/capture context doc (always)
9	3. `framework:learning-harvest` -- Load prior learnings; harvest at session end (always)
10	4. `framework:collaborative-judgment` -- Surface trade-offs in structure, seams, migration sequence (always)
11	5. `framework:clean-code` -- Readability, responsibility boundaries, local craft (always)
12	6. `framework:test-quality` -- Characterization tests and safety net (always)
13	7. `framework:design-first` -- Significant structural changes (conditional)
14	8. `framework:architecture` -- Layer placement and dependency direction (conditional)
15	9. `framework:domain-driven-design` -- Aggregate boundaries and domain behavior (conditional)
16	10. `framework:secure-coding` -- Security-sensitive code (conditional)
17
18	## Workflow
19
20	### Step 1: Establish Refactor Context
21
22	Start from current pain, not preferred abstraction.
23
24	- Identify target area: module, service, aggregate, endpoint path, subsystem
25	- Clarify why refactor needed: mixed responsibilities, duplication, wrong-layer logic, coupling, poor testability, unreadable control flow
26	- Clarify what user expects to improve: simpler structure, correct layer placement, smaller units, clearer domain behavior, easier testing, safer extension points
27	- Use `framework:learning-harvest` Load behavior. Focus hint: "refactoring session — focus: structural health, quality signals".
28	- Use `framework:context-anchoring` Document Discovery to check for existing context doc for affected feature/module
29	- If found → Load it (context-anchoring Load behavior). Honor existing decisions and constraints as active commitments while planning refactor
30	- If not found → Proceed from conversation and current code. Don't block planning on missing context
31
32	End step, summarize intent one sentence:
33
34	> "Refactor X to improve Y while preserving Z."
35
36	STOP: If can't state improvement target and preservation target that clearly, continue clarifying before planning changes.
37
38	Optional persistence check:
39
40	- If refactor substantial, risky, or likely span multiple sessions, ask whether user wants persist approved plan
41	- If relevant context doc already exists and user wants persistence → load and update it
42	- If no relevant doc exists and user wants persistence → propose creating one, confirm doc name per `framework:context-anchoring`, then use as source of truth for approved plan
43	- If user doesn't want persistence or refactor small and local → continue in non-persistent mode. Approval gates still apply; plan simply remains in-session
44
45	### Step 2: Define Preservation Boundaries
46
47	Refactoring changes structure, not behavior. Make preservation contract explicit before proposing structural edits.
48
49	List behaviors that must remain unchanged:
50
51	- Public API contracts and response shapes
52	- Domain invariants and state transitions
53	- Persistence semantics and side effects
54	- Event emission and integration behavior
55	- Authorization and security posture
56	- Error behavior where externally visible
57	- Performance or operational characteristics if part of current contract
58
59	Also list explicit out-of-scope changes:
60
61	- New features
62	- Schema changes
63	- Contract changes
64	- Intentional behavior changes
65	- Unrelated cleanup outside approved area
66
67	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.
68
69	### Step 3: Propose High-Level Structural Plan
70
71	Zero Refactor Rule: no structural code changes until user approves target structure and transition plan.
72
73	For small refactors, plan may be brief. For larger ones, use `framework:design-first` selectively:
74
75	- Start at Level 2 (Components) to define target responsibilities and boundaries
76	- Use Level 3 (Interactions) when data flow or dependency direction will change
77	- Use Level 4 (Contracts) when internal interfaces or seams need formalized
78	- Don't use Level 1 (Capabilities) unless user-facing scope actually changing
79
80	Present:
81
82	- Current structural problems -- what wrong with current shape
83	- Target structure -- what components, classes, functions should exist after refactor
84	- Movement plan -- what logic moves where
85	- Preservation boundaries -- what will stay behaviorally unchanged
86	- Out-of-scope items -- what will not be changed this pass
87
88	End step with explicit ga

People who liked this also viewed

6 picks

Type