go-safe-move-refactor

Moves Go source files between packages while keeping compilation passing at every step.

37|4|Updated Apr 11, 2026
One-click install
npx skills add https://github.com/jmrplens/gitlab-mcp-server --skill go-safe-move-refactor-jmrplens
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: go-safe-move-refactor
Source: https://github.com/jmrplens/gitlab-mcp-server/tree/main/.github/skills/go-safe-move-refactor
Command: npx skills add https://github.com/jmrplens/gitlab-mcp-server --skill go-safe-move-refactor-jmrplens

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Moving Go files between packages often breaks builds mid-refactor because imports, symbol visibility, and type names all change at once. This Skill provides a step-by-step bridge-pattern procedure that keeps go build ./... green after every atomic change. ## Core Features & Use Cases - Bridge-pattern migration: Copy and transform files into the destination package, then add forwarding stubs (type aliases and variable forwarding) in the source package so existing consumers keep compiling. - Symbol and dependency analysis: Catalog exported and unexported symbols with grep and go doc, rename domain-prefixed types (e.g., BranchCreateInput to CreateInput), and export functions that need external callers. - Test and catalog migration: Move test files, swap local helpers for shared testutil utilities, relocate ActionSpecs metadata, and remove stubs only after all consumers are updated. - Use Case: Splitting a monolithic internal/tools package into per-domain sub-packages (branches, commits, pipelines) in verified batches, with lint, build, and test gates after each commit. ## Quick Start Ask the AI to move internal/tools/branches.go into a new internal/tools/branches package using the safe move refactor procedure, keeping the build green at every step.

Frequently Asked Questions about go-safe-move-refactor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I move a Go file to another package without breaking the build?

Copy the file to the destination package, update its package declaration and imports, then add forwarding stubs (type aliases and variable forwarding) in the original package. Verify go build ./... passes after each step before updating consumers and removing stubs.

How to rename Go types when extracting a new package?

Drop the domain prefix since the package name provides the namespace, for example BranchCreateInput becomes CreateInput in the branches package. Keep type aliases in the source package temporarily so existing references like tools.BranchCreateInput still compile.

How do I avoid circular imports when splitting a Go package?

Extract the shared dependency into a separate utility package such as internal/toolutil so both the original and new packages import it instead of each other. This converts a circular tools-branches-tools chain into two clean one-way dependencies.

What should I do with Go tests when moving files between packages?

Copy the test file to the destination, change its package declaration, and update type and function references to the new names. Replace local helpers like newTestClient with shared testutil functions such as testutil.NewTestClient and testutil.RespondJSON instead of duplicating them.

When should I not use forwarding stubs in a Go refactor?

Forwarding stubs are temporary bridges and should be deleted once all consumers import the new package directly and all tests pass. Keeping them long-term hides the real dependency graph and prevents the compiler from flagging stale references.