refactor — Skillopedia

Refactor Skill Quick Ref: Safe, incremental refactoring with test verification at every step. One transformation, one test run, one commit. Never batch. YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it. Modes 1. Target Mode (default) Refactor a specific file, function, or class. You identify what needs improving, plan the steps, and execute them one at a time with test verification. 2. Sweep Mode Find and fix complexity hotspots across a directory, package, or entire project. Runs first to identify targets, then works through them in priority order (highest complexity first). can be: -…

\"\ncheck \"SKILL.md has name: refactor\" \"grep -q '^name: refactor' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions regression testing\" \"grep -qi 'regression' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions incremental or step-wise execution\" \"grep -qiE 'incremental|step|safe' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md requires cross-language removed-symbol sweep\" \"grep -q 'check-removed-symbol-refs.sh' '$SKILL_DIR/SKILL.md'\"\n\necho \"\"; echo \"Results: $PASS passed, $FAIL failed\"\n[ $FAIL -eq 0 ] && exit 0 || exit 1\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":871,"content_sha256":"77c4e1c4f113781c2cad7dd3cf825896f9686e2b23c310eda57ec5544656d8a5"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Refactor Skill","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Quick Ref:","type":"text","marks":[{"type":"strong"}]},{"text":" Safe, incremental refactoring with test verification at every step. One transformation, one test run, one commit. Never batch.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Modes","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1. Target Mode (default)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/refactor \u003cfile-or-function>","type":"text"}]},{"type":"paragraph","content":[{"text":"Refactor a specific file, function, or class. You identify what needs improving, plan the steps, and execute them one at a time with test verification.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2. Sweep Mode","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/refactor --sweep \u003cscope>","type":"text"}]},{"type":"paragraph","content":[{"text":"Find and fix complexity hotspots across a directory, package, or entire project. Runs ","type":"text"},{"text":"/complexity","type":"text","marks":[{"type":"code_inline"}]},{"text":" first to identify targets, then works through them in priority order (highest complexity first).","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003cscope>","type":"text","marks":[{"type":"code_inline"}]},{"text":" can be:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A directory path (","type":"text"},{"text":"cli/internal/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A package name (","type":"text"},{"text":"goals","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"all","type":"text","marks":[{"type":"code_inline"}]},{"text":" (entire project -- use with caution)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3. Extract Mode","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/refactor --extract \u003cpattern>","type":"text"}]},{"type":"paragraph","content":[{"text":"Extract method, class, or module from a target. The ","type":"text"},{"text":"\u003cpattern>","type":"text","marks":[{"type":"code_inline"}]},{"text":" describes what to extract:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"method:\u003cfunction-name>","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- extract a section of a long function into a named helper","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"module:\u003cfile>","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- split a god file into focused modules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"class:\u003cclass-name>","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- extract a class into its own file","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Principle","type":"text"}]},{"type":"paragraph","content":[{"text":"Every refactoring step must be verified by running tests before proceeding to the next step.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"For simplification, de-slop cleanup, over-abstraction removal, or readability-focused refactors, load ","type":"text"},{"text":"references/behavior-preserving-simplification.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/behavior-preserving-simplification.md","title":null}}]},{"text":" before planning transformations.","type":"text"}]},{"type":"paragraph","content":[{"text":"No batching. No \"I'll run tests after all changes.\" Each transformation is atomic:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Transform -> Test -> Pass? -> Commit -> Next\n |\n No -> Revert -> Re-analyze","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Steps","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0: Pre-flight -- Establish Green Baseline","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the full test suite for the target scope BEFORE making any changes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Go projects:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cd cli && go test ./...","type":"text"}]},{"type":"paragraph","content":[{"text":"Python projects:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"pytest","type":"text"}]},{"type":"paragraph","content":[{"text":"If tests fail: STOP.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not refactor code with a broken test suite. Fix the failing tests first, or scope your refactoring to exclude the broken area.","type":"text"}]},{"type":"paragraph","content":[{"text":"Record the baseline:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Number of passing tests","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test execution time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Any skipped tests","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Analyze Target","type":"text"}]},{"type":"paragraph","content":[{"text":"Target mode:","type":"text","marks":[{"type":"strong"}]},{"text":" Read the target code. Identify:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cyclomatic complexity (count branches, loops, conditions)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Function length (lines)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parameter count","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Nesting depth","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code duplication","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Naming clarity","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Sweep mode:","type":"text","marks":[{"type":"strong"}]},{"text":" Run ","type":"text"},{"text":"/complexity","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the scope to get a ranked list of targets:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/complexity \u003cscope>","type":"text"}]},{"type":"paragraph","content":[{"text":"Sort by complexity score descending. Work the worst offenders first.","type":"text"}]},{"type":"paragraph","content":[{"text":"Extract mode:","type":"text","marks":[{"type":"strong"}]},{"text":" Read the target and identify the extraction boundary:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What code moves out?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What interface connects the pieces?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What are the inputs and outputs of the extracted unit?","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Plan Refactoring","type":"text"}]},{"type":"paragraph","content":[{"text":"For each target, produce a numbered list of specific transformations:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"1. Extract lines 45-78 of processConfig() into validateConfig()\n2. Replace nested if/else at line 92 with guard clause + early return\n3. Rename `cfg` to `clusterConfig` for clarity\n4. Inline single-use helper `tmpName()` at line 120","type":"text"}]},{"type":"paragraph","content":[{"text":"For each transformation, identify:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Which tests cover it","type":"text","marks":[{"type":"strong"}]},{"text":" -- grep for test functions that exercise the target","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Risk level","type":"text","marks":[{"type":"strong"}]},{"text":" -- low (rename, formatting), medium (extract, inline), high (interface change, moved code)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Order dependency","type":"text","marks":[{"type":"strong"}]},{"text":" -- does this step depend on a prior step?","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If no tests cover the target: write tests FIRST. Do not refactor untested code.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Execute Step-by-Step","type":"text"}]},{"type":"paragraph","content":[{"text":"For EACH transformation in the plan:","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"3a. Make ONE transformation","type":"text"}]},{"type":"paragraph","content":[{"text":"Apply a single, focused change. Do not combine multiple transformations. Keep the diff minimal and reviewable.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"3b. Run tests immediately","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Go\ncd cli && go test ./...\n\n# Python\npytest\n\n# Or the project-specific test command","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"3c. Evaluate result","type":"text"}]},{"type":"paragraph","content":[{"text":"Tests pass:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit with conventional commit format:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"refactor(\u003cscope>): \u003cdescription>","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"refactor(goals): extract validateConfig from processConfig","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"refactor(hooks): simplify conditional logic in pre-push gate","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"refactor(cli): reduce parameter count in NewCommand","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Tests fail:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Revert the change immediately.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not debug on top of a broken refactor.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-read the failing test to understand what contract was violated.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-analyze the transformation -- was the approach wrong, or was the scope too large?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Retry with a smaller, safer transformation.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"3d. Proceed to next transformation","type":"text"}]},{"type":"paragraph","content":[{"text":"Repeat 3a-3c for each planned step. After completing all steps for a target, move to Step 4.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Post-Refactor Verification","type":"text"}]},{"type":"paragraph","content":[{"text":"After all transformations are complete:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run full test suite","type":"text","marks":[{"type":"strong"}]},{"text":" -- not just the targeted tests, the entire suite:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cd cli && go test ./...","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run complexity analysis","type":"text","marks":[{"type":"strong"}]},{"text":" on changed files:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/complexity \u003cchanged-files>","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare before/after metrics:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Metric","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Before","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"After","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Delta","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cyclomatic complexity","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Lines of code","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Function count","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Max nesting depth","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Test count","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?","type":"text"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify no behavioral change","type":"text","marks":[{"type":"strong"}]},{"text":" -- the refactored code must do exactly what the old code did. If tests were added, they must pass against BOTH the old and new code.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Output Summary","type":"text"}]},{"type":"paragraph","content":[{"text":"Write a refactoring summary to ","type":"text"},{"text":".agents/refactor/","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"mkdir -p .agents/refactor","type":"text"}]},{"type":"paragraph","content":[{"text":"File: ","type":"text"},{"text":".agents/refactor/YYYY-MM-DD-refactor-\u003cscope>.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Content:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# Refactor: \u003cscope>\n\n**Date:** YYYY-MM-DD\n**Mode:** target | sweep | extract\n**Files changed:** \u003ccount>\n\n## Targets\n\n- \u003cfile:function> -- \u003cwhat was done>\n\n## Metrics\n\n| Metric | Before | After | Delta |\n|--------|--------|-------|-------|\n| Cyclomatic complexity | X | Y | -Z |\n| Lines of code | X | Y | -Z |\n| Max nesting depth | X | Y | -Z |\n\n## Transformations Applied\n\n1. \u003cdescription> -- \u003ccommit hash>\n2. \u003cdescription> -- \u003ccommit hash>\n\n## Tests\n\n- Baseline: X passing, Y skipped\n- Final: X passing, Y skipped\n- New tests added: Z\n\n## Learnings\n\n- \u003canything worth noting for future refactors>","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Refactoring Catalog","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Extract Method","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" Function exceeds 30 lines, or a block of code has a clear single purpose.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: longFunction() { ... block A ... block B ... block C ... }\nAfter: longFunction() { doA(); doB(); doC(); }\n doA() { ... block A ... }\n doB() { ... block B ... }\n doC() { ... block C ... }","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Low risk if inputs/outputs are clear. Watch for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shared local variables -- pass as parameters or return as values","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Error handling -- propagate errors from extracted functions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Side effects -- document any mutations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Extract Module","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" A file exceeds 500 lines, or contains multiple unrelated concerns.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: god_file.go (800 lines, 5 concerns)\nAfter: config.go (validation, loading)\n metrics.go (collection, reporting)\n handlers.go (request handling)","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Medium risk. Watch for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Circular imports between new modules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package-level variables shared across concerns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Init functions with ordering dependencies","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Rename","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" A name is ambiguous, misleading, or uses abbreviations that obscure meaning.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: func proc(cfg *C) error\nAfter: func processClusterConfig(config *ClusterConfig) error","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Low risk with tooling. Always:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search for ALL references (including string literals, comments, docs)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update test assertions that reference the old name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check exported symbols -- renaming public APIs is a breaking change","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inline","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" A function or variable adds indirection without adding clarity. Single-use helpers that obscure the flow.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: x := getName(item) // func getName(i Item) string { return i.Name }\nAfter: x := item.Name","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Low risk. Verify the inlined code does not have side effects you are hiding.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Simplify Conditional","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" Nested if/else chains exceed 3 levels, or boolean expressions are complex.","type":"text"}]},{"type":"paragraph","content":[{"text":"Patterns:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Guard clauses:","type":"text","marks":[{"type":"strong"}]},{"text":" Move error/edge cases to top with early return","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Early return:","type":"text","marks":[{"type":"strong"}]},{"text":" Eliminate else branches by returning early","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Table-driven logic:","type":"text","marks":[{"type":"strong"}]},{"text":" Replace long switch/case with map lookup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polymorphism:","type":"text","marks":[{"type":"strong"}]},{"text":" Replace type-based switching with interface dispatch","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before:\n if err != nil {\n if isRetryable(err) {\n if attempts \u003c max {\n retry()\n } else {\n fail()\n }\n } else {\n fail()\n }\n } else {\n succeed()\n }\n\nAfter:\n if err == nil {\n succeed()\n return\n }\n if !isRetryable(err) || attempts >= max {\n fail()\n return\n }\n retry()","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reduce Parameters","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" A function takes more than 4 parameters.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Before: func deploy(name, ns, image string, replicas int, labels map[string]string, timeout time.Duration) error\nAfter: func deploy(opts DeployOptions) error\n\ntype DeployOptions struct {\n Name string\n NS string\n Image string\n Replicas int\n Labels map[string]string\n Timeout time.Duration\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Medium risk -- all callers must be updated. Use the struct field convention from ","type":"text"},{"text":"go.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": grep all call sites and update each one.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remove Dead Code","type":"text"}]},{"type":"paragraph","content":[{"text":"When:","type":"text","marks":[{"type":"strong"}]},{"text":" Functions, variables, constants, or types are defined but never referenced.","type":"text"}]},{"type":"paragraph","content":[{"text":"How to identify:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Go: unused exports\ngo vet ./...\n# Or use staticcheck, deadcode, or unparam tools\n\n# Python: vulture or pylint unused-import\nvulture \u003cdirectory>","type":"text"}]},{"type":"paragraph","content":[{"text":"Safety:","type":"text","marks":[{"type":"strong"}]},{"text":" Low risk for truly dead code. But verify:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not called via reflection or string-based dispatch","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not part of an interface implementation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not used in build tags or conditional compilation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not referenced in external packages (if this is a library)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"CLI command, flag, or cross-language surface removal:","type":"text","marks":[{"type":"strong"}]},{"text":" source-language callers are not enough. Before considering the removal complete, grep every tracked callsite surface that agents commonly forget:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"scripts/check-removed-symbol-refs.sh -- \u003cremoved-command-or-flag>","type":"text"}]},{"type":"paragraph","content":[{"text":"The check searches tracked repo files across source, shell scripts, GitHub workflow YAML, docs, skills, Codex skills, and tests while excluding historical changelogs and release notes. Any remaining hit is a blocker unless it is explicitly excluded with ","type":"text"},{"text":"--exclude","type":"text","marks":[{"type":"code_inline"}]},{"text":" and justified in the closeout.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Guardrails","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What NOT to Refactor","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code you don't understand.","type":"text","marks":[{"type":"strong"}]},{"text":" Read it, test it, understand it -- THEN refactor.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code without tests.","type":"text","marks":[{"type":"strong"}]},{"text":" Write tests first. Refactoring untested code is gambling.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code under active development.","type":"text","marks":[{"type":"strong"}]},{"text":" If someone else is working on it, coordinate first.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance-critical hot paths","type":"text","marks":[{"type":"strong"}]},{"text":" without benchmarks. Measure before and after.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to Stop","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Diminishing returns.","type":"text","marks":[{"type":"strong"}]},{"text":" If complexity dropped from 45 to 12, don't chase 8.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test instability.","type":"text","marks":[{"type":"strong"}]},{"text":" If tests start flaking, stop and stabilize.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scope creep.","type":"text","marks":[{"type":"strong"}]},{"text":" Refactoring should not change behavior. If you find a bug, file an issue -- don't fix it mid-refactor.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Time budget exceeded.","type":"text","marks":[{"type":"strong"}]},{"text":" Set a timebox. Refactoring expands to fill available time.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Red Flags During Refactoring","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tests pass but you changed behavior (test gap -- add a test)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You need to refactor the tests to make them pass (you broke the contract)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The diff is growing beyond what you can review in one sitting (split into smaller PRs)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You are renaming things to match your preference, not for clarity (stop)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"See Also","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/complexity","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- analyze code complexity metrics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/standards","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- language-specific conventions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/vibe","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- validate code quality post-refactor","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/bug-hunt","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- if refactoring uncovers bugs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/implement","type":"text","marks":[{"type":"code_inline"}]},{"text":" -- if refactoring requires new code","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Documents","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/refactor.feature","type":"text","marks":[{"type":"link","attrs":{"href":"references/refactor.feature","title":null}}]},{"text":" — Executable spec: one transformation/one test/one commit, target + hotspot (complexity-first) modes, revert on test fail (soc-qk4b)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/behavior-preserving-simplification.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/behavior-preserving-simplification.md","title":null}}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"refactor","author":"@skillopedia","source":{"stars":375,"repo_name":"agentops","origin_url":"https://github.com/boshu2/agentops/blob/HEAD/skills/refactor/SKILL.md","repo_owner":"boshu2","body_sha256":"06383c94003a0ff4b6a8f2c1182d86c47978ee8938c6aadb6df18f9fe83f3cb4","cluster_key":"889048c69ee74022430f784312fff5ed89e653e1be97bb6dd110dd857912cb73","clean_bundle":{"format":"clean-skill-bundle-v1","source":"boshu2/agentops/skills/refactor/SKILL.md","attachments":[{"id":"f0d40ff3-337b-5e82-8a5e-0c1528868382","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f0d40ff3-337b-5e82-8a5e-0c1528868382/attachment.md","path":"references/behavior-preserving-simplification.md","size":1700,"sha256":"d9c8255e4a185ac23a5bbea91b08d7409e149a789a56425be52853fdd665c756","contentType":"text/markdown; charset=utf-8"},{"id":"8f136475-30c1-5d99-8b70-52b709d0a24c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8f136475-30c1-5d99-8b70-52b709d0a24c/attachment.feature","path":"references/refactor.feature","size":1433,"sha256":"d0d271a040e7ce221bc1620427f1d62de94f2e24cfb4730941ddccf02fd6f265","contentType":"text/plain; charset=utf-8"},{"id":"2d8ef674-f4af-53d1-8492-80c6c1ead000","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2d8ef674-f4af-53d1-8492-80c6c1ead000/attachment.sh","path":"scripts/validate.sh","size":871,"sha256":"77c4e1c4f113781c2cad7dd3cf825896f9686e2b23c310eda57ec5544656d8a5","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"052344ea88819722f4e985eaf8e05bce0b2c4f7fdad81f88871a42d01f3724cb","attachment_count":3,"text_attachments":2,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":1,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/refactor/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"context":{"intent":{"mode":"task"},"window":"fork","sections":{"exclude":["HISTORY"]},"intel_scope":"topic"},"version":"v1","category":"software-engineering","consumes":["complexity","repo-context"],"metadata":{"tier":"execution","dependencies":["standards","complexity","beads"]},"produces":["git-changes"],"practices":["refactoring","legacy-code-seams","design-patterns"],"import_tag":"clean-skills-v1","context_rel":[],"description":"Execute safe refactors.","hexagonal_role":"supporting","output_contract":"code changes with regression verification","skill_api_version":1}},"renderedAt":1782987540741}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.