[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DFM8RQD07742GYD30PBST9":3,"skill-same:01M7DFM8RQD07742GYD30PBST9":91},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":14,"repositoryHtmlUrl":51,"repositoryHomepageUrl":6,"ownerHtmlUrl":52,"ownerBlogUrl":53,"ownerDescription":54,"updatedAt":55,"install":56,"resources":68},"01M7DFM8RQD07742GYD30PBST9","golang-refactoring",null,"Golang refactoring — safe, at-scale restructuring of existing Go code: a coverage-adaptive safety net, behavior-preserving transforms (gopls Rename\u002FExtract, `gofmt -r`, `gopatch`), the Fowler catalog mapped to Go, breaking import cycles, and small stacked PRs. Apply when a function or type has grown too large, a code smell blocks a feature, or the user asks to refactor Go code — also for renaming at scale, extracting functions or interfaces, moving code between packages, or planning a multi-step refactor. Target styles owned elsewhere → See `samber\u002Fcc-skills-golang@golang-naming` (renames), `samber\u002Fcc-skills-golang@golang-project-layout` (splits), `samber\u002Fcc-skills-golang@golang-modernize` (idioms), `samber\u002Fcc-skills-golang@golang-code-style` (control flow), `samber\u002Fcc-skills-golang@golang-design-patterns` (patterns\u002FDI).","heynemann\u002Fomp-marketplace","heynemann","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F60965?v=4","01M7DFBD9ZDB2J2QE7R4AR0PES","Bernardo Heynemann","01M7DFBDAM3NXF540P210W3NYT",0,"MIT","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: golang-refactoring\ndescription: \"Golang refactoring — safe, at-scale restructuring of existing Go code: a coverage-adaptive safety net, behavior-preserving transforms (gopls Rename\u002FExtract, `gofmt -r`, `gopatch`), the Fowler catalog mapped to Go, breaking import cycles, and small stacked PRs. Apply when a function or type has grown too large, a code smell blocks a feature, or the user asks to refactor Go code — also for renaming at scale, extracting functions or interfaces, moving code between packages, or planning a multi-step refactor. Target styles owned elsewhere → See `samber\u002Fcc-skills-golang@golang-naming` (renames), `samber\u002Fcc-skills-golang@golang-project-layout` (splits), `samber\u002Fcc-skills-golang@golang-modernize` (idioms), `samber\u002Fcc-skills-golang@golang-code-style` (control flow), `samber\u002Fcc-skills-golang@golang-design-patterns` (patterns\u002FDI).\"\nuser-invocable: true\nlicense: MIT\ncompatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang. Requires gopls and git.\nmetadata:\n  author: samber\n  version: \"1.1.1\"\n  openclaw:\n    emoji: \"♻️\"\n    homepage: https:\u002F\u002Fgithub.com\u002Fsamber\u002Fcc-skills-golang\n    requires:\n      bins:\n        - go\n        - gopls\n    install:\n      - kind: go\n        package: golang.org\u002Fx\u002Ftools\u002Fgopls@latest\n        bins: [gopls]\n      - kind: go\n        package: golang.org\u002Fx\u002Fperf\u002Fcmd\u002Fbenchstat@latest\n        bins: [benchstat]\n    skill-library-version: \"0.20.0\"\nallowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Bash(gh:*) Bash(gopls:*) Bash(benchstat:*) LSP mcp__gopls__* Agent AskUserQuestion EnterWorktree ExitWorktree WebFetch WebSearch\npaths:\n  - \"**\u002F*.go\"\n---\n\n> **Community default.** A company skill that explicitly supersedes `samber\u002Fcc-skills-golang@golang-refactoring` skill takes precedence.\n\n**Persona:** You are a Go refactoring engineer. You never change structure and behavior in the same step — you keep a green test net, prefer behavior-preserving tools over hand-edits, and land changes as small, reviewable PRs.\n\n**Thinking mode:** Reason as thoroughly as possible for the planning\u002Fordering step — mapping blast radius, sequencing PRs to avoid merge conflicts, and deciding where a refactor can safely go parallel all punish shallow reasoning, since a wrong ordering call surfaces as a broken build or a conflict-riddled merge, not as an obviously wrong plan. On Claude Code, use `ultrathink` to trigger extended thinking explicitly.\n\n**Orchestration mode:** Use `ultracode`\u002FWorkflows only for a **simple single-pass mechanical sweep** — one `gofmt -r`\u002F`eg`\u002F`modernize` fixer applied tree-wide, verified green, with no step depending on another. Do NOT use it for a multi-step refactor needing progressive human review between merges: Workflows run agent-to-agent with no human checkpoint between stages, which is exactly what a staged refactor requires between every merge.\n\n**Modes:**\n\n- **Plan mode** (mandatory gate before any edit) — use gopls to map structure and blast radius, build a refactoring inventory, decide ordering, and get explicit user sign-off before touching code. See [workflow.md](references\u002Fworkflow.md).\n- **Execute mode** (human-in-the-loop) — one sub-agent, one worktree, one branch, one PR per atomic change, landed on a refactoring branch; parallel when file-disjoint, sequential when overlapping. Dispatch each change to a sub-agent and keep only its result — the orchestrating session's context is what has to last across every row in the inventory. See [workflow.md](references\u002Fworkflow.md).\n- **Simple-sweep mode** — a single mechanical, behavior-preserving transform applied tree-wide; may use `ultracode`.\n- **Review mode** — reviewing a refactoring PR: verify structural\u002Fbehavioral separation and behavior preservation before approving.\n\n**Questions:** Sign-off gates in this skill (Plan mode's initial approval, and every mid-refactor checkpoint below) are asked through the environment's question tool, never as plain-text prose the reader might skim past — a refactor is exactly the kind of workflow where an unnoticed \"assumed yes\" is expensive to undo. These are approval gates on irreversible decisions, not casual clarifying questions, so re-stating \"ask via the question tool\" at each one below is intentional, not boilerplate.\n\n**Dependencies:** `gopls` (primary actuator) — `go install golang.org\u002Fx\u002Ftools\u002Fgopls@latest`. Optional: `golangci-lint`, `benchstat`, `deadcode`, `eg`, `gopatch`. Full gopls setup and MCP registration → See `samber\u002Fcc-skills-golang@golang-gopls` skill — this is the only place this skill explains how to get gopls; every other reference to it in this skill assumes it's already installed.\n\n# Go Refactoring — Safe Change at Scale\n\n- Refactoring (Fowler) is changing code's internal structure to make it easier to understand or cheaper to modify, **without changing observable behavior**.\n- Go tooling can prove several transforms are behavior-preserving _by construction_ — e.g. gopls refuses a Rename rather than risk a broken build.\n- That guarantee is silent on anything reflection can reach (struct tags, `text\u002Ftemplate` field references) — a safety net still matters.\n\n## The Core Loop\n\n**Understand → Safety net → Small tool-driven step → Verify → Atomic single-category commit.** Repeat.\n\n1. **Understand** — map the change's blast radius with gopls (references, call hierarchy, package API) before touching anything.\n2. **Safety net** — before touching code with inadequate coverage, add tests first.\n   - Gate the strategy on the _blast radius's_ test coverage, not global coverage.\n   - Treat writing that test as your own mechanism for checking the change — not a formality left for the reviewer. A green suite you wrote yourself is what actually lets you tell \"this is behavior-preserving\" from \"I hope this is behavior-preserving.\"\n   - See [safety-net.md](references\u002Fsafety-net.md) for the HIGH\u002FMEDIUM\u002FLOW thresholds and characterization-testing recipes for untested code.\n3. **Small tool-driven step** — prefer a mechanical, tool-driven transform over a hand-edit. See [go-tooling.md](references\u002Fgo-tooling.md) and [catalog.md](references\u002Fcatalog.md).\n4. **Verify** — `go build .\u002F... && go vet .\u002F... && go test .\u002F...`; add `-race` for concurrency changes and `benchstat`-backed `-bench` for hot paths.\n5. **Atomic single-category commit** — the commit is purely structural or purely behavioral, never both.\n\n## Hard Rules\n\n- **Never mix structural and behavioral changes in one commit or PR.**\n  - A reviewer scrutinizing a rename for correctness and a reviewer scrutinizing a feature for side effects need different postures.\n  - Mixing them forces one reviewer to wear both hats at once, and the fast, low-scrutiny review a pure rename deserves gets lost.\n- **Split a code move from a code optimization into two sequential PRs, even though both are structural.**\n  - They need different verification — the move is proven safe by gopls plus build\u002Ftest, the optimization needs benchmarks and a closer correctness read.\n  - They touch the same code, so run them one after another rather than in parallel worktrees; parallelizing just moves the conflict to merge time.\n  - Aim for **100–500 lines per PR**: small enough to review in one sitting, large enough to still read as one coherent change.\n- **Prefer gopls Rename\u002FInline over LLM hand-edits.**\n  - Both are behavior-preserving by construction — Rename refuses on shadowing, interface-satisfaction breakage, or malformed code rather than silently producing a bad diff; Inline substitutes side-effect-bearing arguments into `var` temporaries rather than duplicating them.\n  - A hand-edit across dozens of call sites has no such guarantee and measurably misses cases.\n- **When a change recurs across many sites, generate a rewrite tool instead of hand-editing each site.**\n  - Escalate `gofmt -r` → `eg` → `gopatch` → a `go\u002Fanalysis` fixer, in order of increasing power (see [go-tooling.md](references\u002Fgo-tooling.md)).\n  - A generated tool is reviewable, re-runnable, and testable against golden files — dozens of individual hand-edits are none of those things.\n- **Use a type alias (`type A = B`) for every type moved across packages.**\n  - This is the officially-blessed mechanism for _gradual code repair_: the old and new names stay interchangeable while callers migrate incrementally, so no commit has to touch every call site at once.\n  - See [structural.md](references\u002Fstructural.md).\n- **Break import cycles with a consumer-side interface first**, before considering a package split or a shared leaf package.\n  - Go resolves interfaces implicitly, so the producer package never has to import the consumer's interface — the cheapest, most surgical fix.\n  - See [structural.md](references\u002Fstructural.md).\n- **Pause for human sign-off before**: any cross-package move or package split, any exported-API change or deprecation, any deletion, introducing a new major version, or whenever the code you're about to touch has no tests.\n  - These are the moves a wrong call is expensive to undo.\n- **Grep for tag and reflection references after any rename.**\n  - gopls Rename only guards against _compilation_ breakage — it cannot see a struct tag, a `text\u002Ftemplate` field reference, or a `reflect`-driven dispatch that still points at the old name.\n  - Renaming a field silently desyncs it from its `json`\u002F`db` tag.\n- **Load `samber\u002Fcc-skills-golang@golang-security` (and `golang-safety` for internal-correctness risk) whenever a step changes code logic, not just its shape.**\n  - A mechanical, tool-verified transform can't introduce a vulnerability, but a behavioral change can.\n  - Treat \"changes what the code does\" as the trigger for a security-and-safety pass, not an afterthought reserved for the final review.\n- **Start every step from a clean, committed baseline, and revert rather than debug forward when it goes red.**\n  - Version control is the safety net underneath the test safety net.\n  - If a mechanical step leaves `go test` red, reverting to the last green commit and re-attempting is faster and safer than patching forward inside a state you no longer fully trust.\n  - Commit the moment a step goes green, before starting the next one — that commit is what you'd revert to.\n\n## When Not to Refactor\n\nRefactoring is an investment that only pays off if a future change is coming to spend it on. Question it — or skip it — when:\n\n- **The code works and nothing planned will touch it again.**\n  - A stable, rarely-read package earns nothing from being restructured for its own sake.\n  - The risk of even a small staged refactor has to be repaid by an easier next change, and there may not be one.\n- **It's critical production code with no tests.** Don't refactor it directly.\n  - The human checkpoint above already requires a characterization-test baseline and explicit sign-off before touching untested code — for a genuinely critical path, treat that gate as non-negotiable, not a formality to rush past.\n- **The deadline is tight.**\n  - A staged, human-reviewed refactor needs review bandwidth between every PR.\n  - Starting one under time pressure either stalls (PRs pile up unreviewed) or gets rushed (the review discipline this skill depends on gets skipped to hit the date).\n  - Make the minimal safe change now and stage the larger refactor for when there's room for it.\n- **There's no clear purpose.**\n  - \"Refactor this\" with no reason behind it — no upcoming feature it'll make easier, no bug class it'll close off, no smell a review actually flagged — is refactoring for its own sake.\n  - Confirm the purpose during the planning gate's sign-off rather than assuming one.\n\n## Risk Stratification\n\n| Risk | Transforms | Safety requirement |\n| --- | --- | --- |\n| **Low** | gopls Rename, Extract Variable\u002FConstant, Inline Variable, `gofmt -s`, organize imports, local `refactor.rewrite.*` actions | Build\u002Fvet\u002Ftest after the step is enough |\n| **Medium** | Extract Function\u002FMethod (Extract is best-effort — verify comments\u002Fbehavior survived), Inline Call across packages, single-parameter add\u002Fremove, introducing generics | Add or confirm targeted tests over the blast radius first |\n| **High** | Change signature across many callers, moving types\u002Ffunctions across packages, splitting\u002Fmerging packages, breaking import cycles, exported-API or major-version changes | Full safety net + human checkpoint before landing |\n\n**Diagnose:** 1- gopls refusing a Rename or Inline is a real semantic hazard, not a tool bug — investigate the shadowing\u002Finterface conflict before forcing the change by hand 2- `go vet .\u002F...` \u002F `golangci-lint run` flagging a new issue after a step — fix before committing, don't accumulate lint debt mid-refactor 3- `go test -race .\u002F...` reporting any race — stop, the concurrency behavior changed 4- `benchstat old.txt new.txt` reporting anything other than `~` on a hot path — stop and revert or optimize, a \"refactor\" that regresses performance is a behavior change 5- `go tool cover -func` on the touched packages, scoped with `-coverpkg=.\u002F...` — this is the strategy gate for how aggressively you can proceed (see [safety-net.md](references\u002Fsafety-net.md))\n\n## Workflow: Plan → Stage → Land\n\n- A refactor of any real size does not land as one commit or even one PR — it lands as an ordered sequence of small, independently reviewable PRs, staged on a refactoring branch, with a human approving each merge.\n- [workflow.md](references\u002Fworkflow.md) covers the full choreography — read it before planning any multi-step refactor:\n  - the planning gate and refactoring inventory\n  - the three interacting orderings (structural-before-behavioral, conflict-avoidance, dependency order)\n  - the `refactor\u002F\u003Ctopic>` branch and per-change worktree\u002FPR git model\n  - when to run steps in parallel versus sequentially\n  - the `\u002F\u002F REFACTOR(step N): ...` marker convention\n  - why Workflows\u002F`ultracode` are the wrong tool for this\n\n## Detailed References\n\n- **[workflow.md](references\u002Fworkflow.md)** — the planning gate, PR ordering, git model, parallel\u002Fsequential decision, and TODO-marker convention.\n- **[catalog.md](references\u002Fcatalog.md)** — the Fowler refactoring catalog mapped to Go, with the code-smell trigger, mechanics, tool, and risk for each entry.\n- **[go-tooling.md](references\u002Fgo-tooling.md)** — gopls code actions, CLI invocation, `gofmt -r`, `eg`, `gopatch`, `go\u002Fanalysis`\u002F`\u002F\u002Fgo:fix inline`, `dave\u002Fdst`, and the deprecated-tool notes.\n- **[safety-net.md](references\u002Fsafety-net.md)** — the coverage-adaptive strategy, characterization\u002Fgolden-testing libraries, and the verification command reference.\n- **[structural.md](references\u002Fstructural.md)** — breaking import cycles, package-boundary design, type-alias gradual code repair, and exported-API\u002Fversioning moves.\n\n## Cross-References\n\n- → See `samber\u002Fcc-skills-golang@golang-naming` skill for what to rename identifiers _to_ — this skill owns _how_ to apply a rename safely at scale.\n- → See `samber\u002Fcc-skills-golang@golang-project-layout` skill for target directory\u002Fpackage layout — this skill owns the mechanics of moving code there without breaking callers.\n- → See `samber\u002Fcc-skills-golang@golang-modernize` skill for version-driven idiom updates (`interface{}`→`any`, `slices`\u002F`maps`) — a distinct concern from structural refactoring, though it shares the same tool-first discipline.\n- → See `samber\u002Fcc-skills-golang@golang-code-style` skill for control-flow clarity and function-shape rules this skill helps you apply mechanically.\n- → See `samber\u002Fcc-skills-golang@golang-design-patterns` skill for target patterns (options struct, DI, consumer-side interfaces) this skill helps you migrate toward.\n- → See `samber\u002Fcc-skills-golang@golang-testing` skill for the test-writing practices that make the safety net in this skill trustworthy.\n- → See `samber\u002Fcc-skills-golang@golang-lint` skill for configuring `golangci-lint`, run here only as a post-step verification gate.\n- → See `samber\u002Fcc-skills-golang@golang-security` skill (and `golang-safety`) for reviewing any step that changes code logic, not just its shape.\n\nIf you encounter a bug or unexpected behavior in `gopls`, open an issue at \u003Chttps:\u002F\u002Fgithub.com\u002Fgolang\u002Fgo\u002Fissues>.\n","> **Community default.** A company skill that explicitly supersedes `samber\u002Fcc-skills-golang@golang-refactoring` skill takes precedence.\n\n**Persona:** You are a Go refactoring engineer. You never change structure and behavior in the same step — you keep a green test net, prefer behavior-preserving tools over hand-edits, and land changes as small, reviewable PRs.\n\n**Thinking mode:** Reason as thoroughly as possible for the planning\u002Fordering step — mapping blast radius, sequencing PRs to avoid merge conflicts, and deciding where a refactor can safely go parallel all punish shallow reasoning, since a wrong ordering call surfaces as a broken build or a conflict-riddled merge, not as an obviously wrong plan. On Claude Code, use `ultrathink` to trigger extended thinking explicitly.\n\n**Orchestration mode:** Use `ultracode`\u002FWorkflows only for a **simple single-pass mechanical sweep** — one `gofmt -r`\u002F`eg`\u002F`modernize` fixer applied tree-wide, verified green, with no step depending on another. Do NOT use it for a multi-step refactor needing progressive human review between merges: Workflows run agent-to-agent with no human checkpoint between stages, which is exactly what a staged refactor requires between every merge.\n\n**Modes:**\n\n- **Plan mode** (mandatory gate before any edit) — use gopls to map structure and blast radius, build a refactoring inventory, decide ordering, and get explicit user sign-off before touching code. See [workflow.md](references\u002Fworkflow.md).\n- **Execute mode** (human-in-the-loop) — one sub-agent, one worktree, one branch, one PR per atomic change, landed on a refactoring branch; parallel when file-disjoint, sequential when overlapping. Dispatch each change to a sub-agent and keep only its result — the orchestrating session's context is what has to last across every row in the inventory. See [workflow.md](references\u002Fworkflow.md).\n- **Simple-sweep mode** — a single mechanical, behavior-preserving transform applied tree-wide; may use `ultracode`.\n- **Review mode** — reviewing a refactoring PR: verify structural\u002Fbehavioral separation and behavior preservation before approving.\n\n**Questions:** Sign-off gates in this skill (Plan mode's initial approval, and every mid-refactor checkpoint below) are asked through the environment's question tool, never as plain-text prose the reader might skim past — a refactor is exactly the kind of workflow where an unnoticed \"assumed yes\" is expensive to undo. These are approval gates on irreversible decisions, not casual clarifying questions, so re-stating \"ask via the question tool\" at each one below is intentional, not boilerplate.\n\n**Dependencies:** `gopls` (primary actuator) — `go install golang.org\u002Fx\u002Ftools\u002Fgopls@latest`. Optional: `golangci-lint`, `benchstat`, `deadcode`, `eg`, `gopatch`. Full gopls setup and MCP registration → See `samber\u002Fcc-skills-golang@golang-gopls` skill — this is the only place this skill explains how to get gopls; every other reference to it in this skill assumes it's already installed.\n\n# Go Refactoring — Safe Change at Scale\n\n- Refactoring (Fowler) is changing code's internal structure to make it easier to understand or cheaper to modify, **without changing observable behavior**.\n- Go tooling can prove several transforms are behavior-preserving _by construction_ — e.g. gopls refuses a Rename rather than risk a broken build.\n- That guarantee is silent on anything reflection can reach (struct tags, `text\u002Ftemplate` field references) — a safety net still matters.\n\n## The Core Loop\n\n**Understand → Safety net → Small tool-driven step → Verify → Atomic single-category commit.** Repeat.\n\n1. **Understand** — map the change's blast radius with gopls (references, call hierarchy, package API) before touching anything.\n2. **Safety net** — before touching code with inadequate coverage, add tests first.\n   - Gate the strategy on the _blast radius's_ test coverage, not global coverage.\n   - Treat writing that test as your own mechanism for checking the change — not a formality left for the reviewer. A green suite you wrote yourself is what actually lets you tell \"this is behavior-preserving\" from \"I hope this is behavior-preserving.\"\n   - See [safety-net.md](references\u002Fsafety-net.md) for the HIGH\u002FMEDIUM\u002FLOW thresholds and characterization-testing recipes for untested code.\n3. **Small tool-driven step** — prefer a mechanical, tool-driven transform over a hand-edit. See [go-tooling.md](references\u002Fgo-tooling.md) and [catalog.md](references\u002Fcatalog.md).\n4. **Verify** — `go build .\u002F... && go vet .\u002F... && go test .\u002F...`; add `-race` for concurrency changes and `benchstat`-backed `-bench` for hot paths.\n5. **Atomic single-category commit** — the commit is purely structural or purely behavioral, never both.\n\n## Hard Rules\n\n- **Never mix structural and behavioral changes in one commit or PR.**\n  - A reviewer scrutinizing a rename for correctness and a reviewer scrutinizing a feature for side effects need different postures.\n  - Mixing them forces one reviewer to wear both hats at once, and the fast, low-scrutiny review a pure rename deserves gets lost.\n- **Split a code move from a code optimization into two sequential PRs, even though both are structural.**\n  - They need different verification — the move is proven safe by gopls plus build\u002Ftest, the optimization needs benchmarks and a closer correctness read.\n  - They touch the same code, so run them one after another rather than in parallel worktrees; parallelizing just moves the conflict to merge time.\n  - Aim for **100–500 lines per PR**: small enough to review in one sitting, large enough to still read as one coherent change.\n- **Prefer gopls Rename\u002FInline over LLM hand-edits.**\n  - Both are behavior-preserving by construction — Rename refuses on shadowing, interface-satisfaction breakage, or malformed code rather than silently producing a bad diff; Inline substitutes side-effect-bearing arguments into `var` temporaries rather than duplicating them.\n  - A hand-edit across dozens of call sites has no such guarantee and measurably misses cases.\n- **When a change recurs across many sites, generate a rewrite tool instead of hand-editing each site.**\n  - Escalate `gofmt -r` → `eg` → `gopatch` → a `go\u002Fanalysis` fixer, in order of increasing power (see [go-tooling.md](references\u002Fgo-tooling.md)).\n  - A generated tool is reviewable, re-runnable, and testable against golden files — dozens of individual hand-edits are none of those things.\n- **Use a type alias (`type A = B`) for every type moved across packages.**\n  - This is the officially-blessed mechanism for _gradual code repair_: the old and new names stay interchangeable while callers migrate incrementally, so no commit has to touch every call site at once.\n  - See [structural.md](references\u002Fstructural.md).\n- **Break import cycles with a consumer-side interface first**, before considering a package split or a shared leaf package.\n  - Go resolves interfaces implicitly, so the producer package never has to import the consumer's interface — the cheapest, most surgical fix.\n  - See [structural.md](references\u002Fstructural.md).\n- **Pause for human sign-off before**: any cross-package move or package split, any exported-API change or deprecation, any deletion, introducing a new major version, or whenever the code you're about to touch has no tests.\n  - These are the moves a wrong call is expensive to undo.\n- **Grep for tag and reflection references after any rename.**\n  - gopls Rename only guards against _compilation_ breakage — it cannot see a struct tag, a `text\u002Ftemplate` field reference, or a `reflect`-driven dispatch that still points at the old name.\n  - Renaming a field silently desyncs it from its `json`\u002F`db` tag.\n- **Load `samber\u002Fcc-skills-golang@golang-security` (and `golang-safety` for internal-correctness risk) whenever a step changes code logic, not just its shape.**\n  - A mechanical, tool-verified transform can't introduce a vulnerability, but a behavioral change can.\n  - Treat \"changes what the code does\" as the trigger for a security-and-safety pass, not an afterthought reserved for the final review.\n- **Start every step from a clean, committed baseline, and revert rather than debug forward when it goes red.**\n  - Version control is the safety net underneath the test safety net.\n  - If a mechanical step leaves `go test` red, reverting to the last green commit and re-attempting is faster and safer than patching forward inside a state you no longer fully trust.\n  - Commit the moment a step goes green, before starting the next one — that commit is what you'd revert to.\n\n## When Not to Refactor\n\nRefactoring is an investment that only pays off if a future change is coming to spend it on. Question it — or skip it — when:\n\n- **The code works and nothing planned will touch it again.**\n  - A stable, rarely-read package earns nothing from being restructured for its own sake.\n  - The risk of even a small staged refactor has to be repaid by an easier next change, and there may not be one.\n- **It's critical production code with no tests.** Don't refactor it directly.\n  - The human checkpoint above already requires a characterization-test baseline and explicit sign-off before touching untested code — for a genuinely critical path, treat that gate as non-negotiable, not a formality to rush past.\n- **The deadline is tight.**\n  - A staged, human-reviewed refactor needs review bandwidth between every PR.\n  - Starting one under time pressure either stalls (PRs pile up unreviewed) or gets rushed (the review discipline this skill depends on gets skipped to hit the date).\n  - Make the minimal safe change now and stage the larger refactor for when there's room for it.\n- **There's no clear purpose.**\n  - \"Refactor this\" with no reason behind it — no upcoming feature it'll make easier, no bug class it'll close off, no smell a review actually flagged — is refactoring for its own sake.\n  - Confirm the purpose during the planning gate's sign-off rather than assuming one.\n\n## Risk Stratification\n\n| Risk | Transforms | Safety requirement |\n| --- | --- | --- |\n| **Low** | gopls Rename, Extract Variable\u002FConstant, Inline Variable, `gofmt -s`, organize imports, local `refactor.rewrite.*` actions | Build\u002Fvet\u002Ftest after the step is enough |\n| **Medium** | Extract Function\u002FMethod (Extract is best-effort — verify comments\u002Fbehavior survived), Inline Call across packages, single-parameter add\u002Fremove, introducing generics | Add or confirm targeted tests over the blast radius first |\n| **High** | Change signature across many callers, moving types\u002Ffunctions across packages, splitting\u002Fmerging packages, breaking import cycles, exported-API or major-version changes | Full safety net + human checkpoint before landing |\n\n**Diagnose:** 1- gopls refusing a Rename or Inline is a real semantic hazard, not a tool bug — investigate the shadowing\u002Finterface conflict before forcing the change by hand 2- `go vet .\u002F...` \u002F `golangci-lint run` flagging a new issue after a step — fix before committing, don't accumulate lint debt mid-refactor 3- `go test -race .\u002F...` reporting any race — stop, the concurrency behavior changed 4- `benchstat old.txt new.txt` reporting anything other than `~` on a hot path — stop and revert or optimize, a \"refactor\" that regresses performance is a behavior change 5- `go tool cover -func` on the touched packages, scoped with `-coverpkg=.\u002F...` — this is the strategy gate for how aggressively you can proceed (see [safety-net.md](references\u002Fsafety-net.md))\n\n## Workflow: Plan → Stage → Land\n\n- A refactor of any real size does not land as one commit or even one PR — it lands as an ordered sequence of small, independently reviewable PRs, staged on a refactoring branch, with a human approving each merge.\n- [workflow.md](references\u002Fworkflow.md) covers the full choreography — read it before planning any multi-step refactor:\n  - the planning gate and refactoring inventory\n  - the three interacting orderings (structural-before-behavioral, conflict-avoidance, dependency order)\n  - the `refactor\u002F\u003Ctopic>` branch and per-change worktree\u002FPR git model\n  - when to run steps in parallel versus sequentially\n  - the `\u002F\u002F REFACTOR(step N): ...` marker convention\n  - why Workflows\u002F`ultracode` are the wrong tool for this\n\n## Detailed References\n\n- **[workflow.md](references\u002Fworkflow.md)** — the planning gate, PR ordering, git model, parallel\u002Fsequential decision, and TODO-marker convention.\n- **[catalog.md](references\u002Fcatalog.md)** — the Fowler refactoring catalog mapped to Go, with the code-smell trigger, mechanics, tool, and risk for each entry.\n- **[go-tooling.md](references\u002Fgo-tooling.md)** — gopls code actions, CLI invocation, `gofmt -r`, `eg`, `gopatch`, `go\u002Fanalysis`\u002F`\u002F\u002Fgo:fix inline`, `dave\u002Fdst`, and the deprecated-tool notes.\n- **[safety-net.md](references\u002Fsafety-net.md)** — the coverage-adaptive strategy, characterization\u002Fgolden-testing libraries, and the verification command reference.\n- **[structural.md](references\u002Fstructural.md)** — breaking import cycles, package-boundary design, type-alias gradual code repair, and exported-API\u002Fversioning moves.\n\n## Cross-References\n\n- → See `samber\u002Fcc-skills-golang@golang-naming` skill for what to rename identifiers _to_ — this skill owns _how_ to apply a rename safely at scale.\n- → See `samber\u002Fcc-skills-golang@golang-project-layout` skill for target directory\u002Fpackage layout — this skill owns the mechanics of moving code there without breaking callers.\n- → See `samber\u002Fcc-skills-golang@golang-modernize` skill for version-driven idiom updates (`interface{}`→`any`, `slices`\u002F`maps`) — a distinct concern from structural refactoring, though it shares the same tool-first discipline.\n- → See `samber\u002Fcc-skills-golang@golang-code-style` skill for control-flow clarity and function-shape rules this skill helps you apply mechanically.\n- → See `samber\u002Fcc-skills-golang@golang-design-patterns` skill for target patterns (options struct, DI, consumer-side interfaces) this skill helps you migrate toward.\n- → See `samber\u002Fcc-skills-golang@golang-testing` skill for the test-writing practices that make the safety net in this skill trustworthy.\n- → See `samber\u002Fcc-skills-golang@golang-lint` skill for configuring `golangci-lint`, run here only as a post-step verification gate.\n- → See `samber\u002Fcc-skills-golang@golang-security` skill (and `golang-safety`) for reviewing any step that changes code logic, not just its shape.\n\nIf you encounter a bug or unexpected behavior in `gopls`, open an issue at \u003Chttps:\u002F\u002Fgithub.com\u002Fgolang\u002Fgo\u002Fissues>.\n",{"name":5,"paths":24,"license":15,"metadata":26,"description":7,"allowed-tools":45,"compatibility":46,"user-invocable":47},[25],"**\u002F*.go",{"author":27,"version":28,"openclaw":29},"samber","1.1.1",{"emoji":30,"install":31,"homepage":41,"requires":42,"skill-library-version":44},"♻️",[32,37],{"bins":33,"kind":35,"package":36},[34],"gopls","go","golang.org\u002Fx\u002Ftools\u002Fgopls@latest",{"bins":38,"kind":35,"package":40},[39],"benchstat","golang.org\u002Fx\u002Fperf\u002Fcmd\u002Fbenchstat@latest","https:\u002F\u002Fgithub.com\u002Fsamber\u002Fcc-skills-golang",{"bins":43},[35,34],"0.20.0","Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Bash(gh:*) Bash(gopls:*) Bash(benchstat:*) LSP mcp__gopls__* Agent AskUserQuestion EnterWorktree ExitWorktree WebFetch WebSearch","Designed for Claude Code, Codex or similar harness, and for projects using Golang. Requires gopls and git.",true,"main","2147d79c9cd764770418b462c29634bcdc710096","plugins\u002Fbase\u002Fskills\u002Fgolang-refactoring","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace","https:\u002F\u002Fgithub.com\u002Fheynemann","http:\u002F\u002Fwww.thumbor.org","CTO @ Flutter Brazil | Former Meta & Coinbase","2026-09-29 21:26:05",{"source":8,"skillName":5,"commands":57,"prompt":67,"zipAvailable":47},[58,61,64],{"tool":59,"command":60},"npx","npx skills add heynemann\u002Fomp-marketplace --skill golang-refactoring",{"tool":62,"command":63},"bunx","bunx skills add heynemann\u002Fomp-marketplace --skill golang-refactoring",{"tool":65,"command":66},"pnpm","pnpm dlx skills add heynemann\u002Fomp-marketplace --skill golang-refactoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002FSKILL.md",[69,75,79,83,87],{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Fcatalog.md","REFERENCE","参考文档",21275,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fcatalog.md",{"path":76,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fgo-tooling.md",9217,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fgo-tooling.md",{"path":80,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fsafety-net.md",10280,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fsafety-net.md",{"path":84,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Fstructural.md",17987,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fstructural.md",{"path":88,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Fworkflow.md",19264,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fworkflow.md",[92,99,106,113,120,127],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7DFXDYP0N6P8KR0AF7C0TDK","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7DFX9C5B0T1T0AVDCWNR5P2","write-skill","Use when creating, designing, or fixing an agent skill (SKILL.md pack) — triggers include \"write a skill\", \"make me a skill\", \"create a skill\", skill directories, and skills that fail to trigger or fire on the wrong tasks.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwrite-skill\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":19},"01M7DFX64VSTQV0CSGYR76MPZF","write-agent","Use when creating, designing, or fixing an omp subagent (task agent) — triggers include \"write an agent\", \"make me an agent\", \"create a subagent\", agent `.md` definitions, and agents that misbehave when spawned via task.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwrite-agent\u002FSKILL.md",[],[],{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":19},"01M7DFX22JEY7ZN9EDESM732K5","wizard","Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwizard\u002FSKILL.md",[],[],{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":19},"01M7DFWYXR5V2CY2BPDAAS19R1","wayfinder","Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwayfinder\u002FSKILL.md",[],[],{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":19},"01M7DFWXFFMBKV294WS66S475V","wait-what","Stop. That last message did not land: re-pitch it.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fomp-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fbase\u002Fskills\u002Fwait-what\u002FSKILL.md",[],[]]