From workflow-tools
This skill should be used when the user asks to "refactor this package", "reorganize this code", "split this file", "this code is a mess", "too many files", "simplify this module", "restructure this", or mentions god structs, god components, god classes, package organization, module structure, or code that is hard to navigate. Unlike the code-cleanup skill (which removes dead code and tests), this skill restructures working code for clarity and maintainability.
How this skill is triggered — by the user, by Claude, or both
Slash command
/workflow-tools:refactorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Restructure working code that has grown tangled over time. Focused on architectural patterns that emerge as code evolves: mixed concerns, accumulated dependencies, tangled relationships, organic complexity.
Restructure working code that has grown tangled over time. Focused on architectural patterns that emerge as code evolves: mixed concerns, accumulated dependencies, tangled relationships, organic complexity.
This is not a linter. The primary focus is structural problems that require understanding the code's architecture and relationships. Complexity scores and idiomatic pattern violations are useful signals for finding problem areas, but always explain the underlying structural issue, not just the number.
Identify what to refactor and the primary language. Scope can be:
Detect the language from file extensions, then load the appropriate reference:
Map the current state before proposing changes. Understand how the code flows:
Present findings as structural observations, not metrics. Use this format:
## Refactoring Report
### Mixed Concerns
- **pkg/server.go** mixes HTTP handler routing, request validation, business logic, and database queries. These grew together but should be separate layers.
### Accumulated Dependencies
- **pkg/models.go:App** has become a god struct. Every new feature added a field. It now holds the database, cache, logger, mailer, and 8 service references. Nothing forces a developer to think about which dependencies a function actually needs.
### Tangled Relationships
- **pkg/auth.go** imports **pkg/users.go** which imports **pkg/auth.go** via a shared type. The circular dependency is worked around with an interface, but the real issue is that auth and user management are different concerns living in the same package.
### Hidden Coupling
- **pkg/globals.go** defines package-level state that 6 files depend on implicitly. Changing initialization order breaks things in non-obvious ways.
End with: "Found X structural issues. Proposed refactoring plan below."
After the report, propose a concrete plan with the target structure:
## Proposed Structure
pkg/
├── handler.go (HTTP handlers, delegates to services)
├── service.go (business logic, receives dependencies)
├── models.go (domain types only)
└── internal/
├── auth/ (extracted: auth has its own concern)
└── storage/ (extracted: storage is a separate dependency)
## Steps
1. Extract auth types and middleware into internal/auth/ (breaks the circular dep)
2. Move storage logic into internal/storage/
3. Split server.go by layer: handlers stay, business logic moves to service.go
4. Break App god struct into focused components with explicit dependencies
5. Remove globals.go, wire dependencies in main
Each step should describe why, not just what. The user needs to understand the reasoning.
After the user confirms the plan, apply changes one step at a time:
utils, common, helpers, or shared packages. Redistribute to domain-specific locations.npx claudepluginhub denisraison/claude-plugins --plugin workflow-toolsApplies disciplined refactoring in small, verifiable steps to improve code structure without changing behavior: extract functions, rename, move code.
Executes safe, incremental refactoring with test verification at each step. Supports target, sweep, and extract modes for files, functions, or complexity hotspots.
Refactors code while preserving behavior: cleanup, modularize, deduplicate, rename, simplify structure in small reversible steps. Not for behavioral changes.