---
name: go-package-refactoring-tool
description: "A concrete plan to untangle a Go package: the import cycles and coupling found with file references, the new package boundaries, the order to move code so the build stays green at every step, and the interfaces that make it testable. Use when a Go package has import cycles, a god struct, global state, or too many exports and needs a step-by-step restructure plan that keeps the build green. Do not use for scaffolding a new package, or line-level cleanups like renaming variables inside one file. Related topics: coding, package."
---

# Go Package Refactoring Tool

A concrete plan to untangle a Go package: the import cycles and coupling found with file references, the new package boundaries, the order to move code so the build stays green at every step, and the interfaces that make it testable.

## When to use

Use this skill when a Go package has import cycles, a god struct, global state, or too many exports and needs a step-by-step restructure plan that keeps the build green. Do not use it for scaffolding a new package, or line-level cleanups like renaming variables inside one file.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Build the import graph from the supplied layout and list every cycle and over-coupled package with the files and identifiers involved.
3. Define the new package boundaries by what changes together and what callers need, named for what they provide, within the files-per-package limit.
4. Resolve each cycle by moving the shared type to its owner or by introducing a consumer-side interface, and replace global state with constructor parameters.
5. Sequence the moves so go build and go test pass after every step, using forwarding aliases where exported names must survive.
6. Write the new interfaces and changed signatures as Go code and flag any step that touches an API the constraints protect.

## Inputs

- **Package path** (free text, e.g. "github.com/acme/app/internal/service")
- **Package layout and imports** (longer free text)
- **Primary goal** (choose one: Resolve circular dependencies, Reduce coupling, Improve testability, Optimize build time)
- **Patterns to remove** (choose any: Import cycles, Large single files, Global state usage, Excessive exports, God structs, Init functions with side effects)
- **Target Go version** (free text, e.g. "1.22")
- **Constraints** (longer free text)
- **Maximum files per package** (number from 1 to 20)

## Output

A markdown plan with three sections: Problems found (with file references), Migration steps (numbered, each leaving the build green), and Code (new interfaces and changed signatures in Go blocks).

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Go Package Refactoring Tool

Plan a restructure of my Go package that removes coupling without breaking the build.

#### Details
- Package path: {{Package path}}
- Package layout and imports: {{Package layout and imports}}
- Primary goal: {{Primary goal}}
- Patterns to remove: {{Patterns to remove}}
- Target Go version: {{Target Go version}}
- Constraints: {{Constraints}}
- Maximum files per package: {{Maximum files per package}}

Draw the import graph first and name each cycle and each package that knows too much, with the files and identifiers involved, since the plan is only as good as the diagnosis. Decide the new package boundaries by what changes together and what callers need, keeping packages small and named for what they provide rather than for layers (no util or common). Break cycles by moving the shared type to the package that owns it or by defining a small consumer-side interface, which also makes the code testable with fakes. Replace global state with values passed in through constructors. Order the moves so the build and tests pass after every step: add the new package, move code with forwarding aliases where exported names must survive, update callers, then delete the old location. Give the new interfaces and changed signatures as Go code. Flag any step that changes an exported API the constraints protect.

## Pitfalls

- Creating a util or common package to break a cycle, which becomes a new dumping ground that everything imports.
- Defining interfaces on the producer side with every method, when Go idiom wants small interfaces declared where they are consumed.
- Moving everything in one commit, so a single compile error blocks the whole refactor instead of one step.
