[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CFKPJ2CQ6ESSXKKS2ZT12T":3,"skill-same:01M6CFKPJ2CQ6ESSXKKS2ZT12T":117},{"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":26,"publishedAt":47,"linkOnly":48,"markdownContent":49,"markdownBody":50,"frontMatter":51,"refName":75,"commitSha":76,"skillDirectory":77,"forksCount":78,"repositoryHtmlUrl":79,"repositoryHomepageUrl":6,"ownerHtmlUrl":80,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":81,"install":82,"resources":94},"01M6CFKPJ2CQ6ESSXKKS2ZT12T","golang-refactoring",null,"Golang refactoring — the safe, at-scale process for restructuring existing Go code: a coverage-adaptive safety net, tool-driven behavior-preserving transforms (gopls Rename\u002FInline\u002FExtract, `gofmt -r`, `eg`, `gopatch`, `go\u002Fanalysis` fixers), the Fowler catalog mapped to Go, breaking import cycles, moving types across packages, and a human-in-the-loop workflow of small stacked PRs on a refactoring branch. Apply when code is hard to maintain, a function\u002Ftype has grown too large, a code smell needs fixing, adding a feature is blocked by the current structure, or the user asks to clean up, refactor, or improve Go code — also for renaming at scale, extracting functions\u002Finterfaces, moving code between packages, splitting packages, or planning a multi-step refactor. Target styles owned elsewhere → See `golang-naming` (renames), `@golang-project-layout` (splits), `@golang-modernize` (idioms), `@golang-code-style` (control flow), `@golang-design-patterns` (patterns\u002FDI).","rockcookies\u002Fskills","rockcookies","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F3498265?v=4","01M6CF9C16X3SDSKZX6ANH7HQM","Jacob He","01M6CF9C53JP821FCW6R9B00AJ",1,"MIT","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000007","代码审查","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46],"golang refactoring","golang","refactoring","loop","clean","up","coverage","write","read","branch","projects","design","improve","gopls","Bash","analysis","code","packages","workflow","MCP","2026-11-10 10:12:30",false,"---\nname: golang-refactoring\ndescription: >-\n  Golang refactoring — the safe, at-scale process for restructuring existing Go\n  code: a coverage-adaptive safety net, tool-driven behavior-preserving\n  transforms (gopls Rename\u002FInline\u002FExtract, `gofmt -r`, `eg`, `gopatch`,\n  `go\u002Fanalysis` fixers), the Fowler catalog mapped to Go, breaking import\n  cycles, moving types across packages, and a human-in-the-loop workflow of\n  small stacked PRs on a refactoring branch. Apply when code is hard to\n  maintain, a function\u002Ftype has grown too large, a code smell needs fixing,\n  adding a feature is blocked by the current structure, or the user asks to\n  clean up, refactor, or improve Go code — also for renaming at scale,\n  extracting functions\u002Finterfaces, moving code between packages, splitting\n  packages, or planning a multi-step refactor. Target styles owned elsewhere →\n  See `golang-naming` (renames), `@golang-project-layout` (splits),\n  `@golang-modernize` (idioms), `@golang-code-style` (control flow),\n  `@golang-design-patterns` (patterns\u002FDI).\nuser-invocable: true\nlicense: MIT\ncompatibility: >-\n  Designed for Claude Code, Codex or similar harness, and for projects using\n  Golang. Requires gopls and git.\nmetadata:\n  author: samber\n  version: 1.1.0\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:\n          - gopls\n      - kind: go\n        package: golang.org\u002Fx\u002Fperf\u002Fcmd\u002Fbenchstat@latest\n        bins:\n          - benchstat\n    skill-library-version: 0.20.0\nallowed-tools: >-\n  Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*)\n  Bash(gh:*) Bash(gopls:*) Bash(benchstat:*) LSP mcp__gopls__* Agent\n  AskUserQuestion EnterWorktree ExitWorktree WebFetch WebSearch\npaths:\n  - '**\u002F*.go'\n---\n\n> **Community default.** A company skill that explicitly supersedes `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 `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 `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 `golang-naming` skill for what to rename identifiers _to_ — this skill owns _how_ to apply a rename safely at scale.\n- → See `golang-project-layout` skill for target directory\u002Fpackage layout — this skill owns the mechanics of moving code there without breaking callers.\n- → See `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 `golang-code-style` skill for control-flow clarity and function-shape rules this skill helps you apply mechanically.\n- → See `golang-design-patterns` skill for target patterns (options struct, DI, consumer-side interfaces) this skill helps you migrate toward.\n- → See `golang-testing` skill for the test-writing practices that make the safety net in this skill trustworthy.\n- → See `golang-lint` skill for configuring `golangci-lint`, run here only as a post-step verification gate.\n- → See `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 `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 `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 `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 `golang-naming` skill for what to rename identifiers _to_ — this skill owns _how_ to apply a rename safely at scale.\n- → See `golang-project-layout` skill for target directory\u002Fpackage layout — this skill owns the mechanics of moving code there without breaking callers.\n- → See `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 `golang-code-style` skill for control-flow clarity and function-shape rules this skill helps you apply mechanically.\n- → See `golang-design-patterns` skill for target patterns (options struct, DI, consumer-side interfaces) this skill helps you migrate toward.\n- → See `golang-testing` skill for the test-writing practices that make the safety net in this skill trustworthy.\n- → See `golang-lint` skill for configuring `golangci-lint`, run here only as a post-step verification gate.\n- → See `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":52,"license":15,"metadata":54,"description":7,"allowed-tools":72,"compatibility":73,"user-invocable":74},[53],"**\u002F*.go",{"author":55,"version":56,"openclaw":57},"samber","1.1.0",{"emoji":58,"install":59,"homepage":68,"requires":69,"skill-library-version":71},"♻️",[60,64],{"bins":61,"kind":62,"package":63},[40],"go","golang.org\u002Fx\u002Ftools\u002Fgopls@latest",{"bins":65,"kind":62,"package":67},[66],"benchstat","golang.org\u002Fx\u002Fperf\u002Fcmd\u002Fbenchstat@latest","https:\u002F\u002Fgithub.com\u002Fsamber\u002Fcc-skills-golang",{"bins":70},[62,40],"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","c349be0704bffe54a7191d1412faf564b08983ca","skills\u002Fsamber-golang\u002Fgolang-refactoring",0,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills","https:\u002F\u002Fgithub.com\u002Frockcookies","2026-11-12 14:42:52",{"source":8,"skillName":5,"commands":83,"prompt":93,"zipAvailable":74},[84,87,90],{"tool":85,"command":86},"npx","npx skills add rockcookies\u002Fskills --skill golang-refactoring",{"tool":88,"command":89},"bunx","bunx skills add rockcookies\u002Fskills --skill golang-refactoring",{"tool":91,"command":92},"pnpm","pnpm dlx skills add rockcookies\u002Fskills --skill golang-refactoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002FSKILL.md",[95,101,105,109,113],{"path":96,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":99,"sourceHtmlUrl":100},"references\u002Fcatalog.md","REFERENCE","参考文档",19942,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002Freferences\u002Fcatalog.md",{"path":102,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":103,"sourceHtmlUrl":104},"references\u002Fgo-tooling.md",8013,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002Freferences\u002Fgo-tooling.md",{"path":106,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":107,"sourceHtmlUrl":108},"references\u002Fsafety-net.md",10184,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002Freferences\u002Fsafety-net.md",{"path":110,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":111,"sourceHtmlUrl":112},"references\u002Fstructural.md",16817,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002Freferences\u002Fstructural.md",{"path":114,"resourceType":97,"resourceTypeDesc":98,"sizeBytes":115,"sourceHtmlUrl":116},"references\u002Fworkflow.md",18477,"https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fsamber-golang\u002Fgolang-refactoring\u002Freferences\u002Fworkflow.md",[118,141,159,182,194,208],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":47},"01M6WMNKD3Y4H9FGM8Q901F507","hierarchical-agents-md","层级 AGENTS.md \u002F README.md：init、update、audit、reorganize、trim。 初始化 Agent 指令、代码改动后同步文档、检查文档漂移、重组仓库文档层级、精简规则与 Skills。 Not for 写业务代码或生成文档站点。","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcustom\u002Fhierarchical-agents-md\u002FSKILL.md",[],[125,126,127,128,129,130,131,44,132,133,134,135,136,137,138,139,140],"hierarchical agents md","agents md","party","init","third-party","true","git","change","maintenance","初始化","文档","audit","for","README","update","python",{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":150,"publishedAt":47},"01M6CFS6BRTQPFZCDHQP97HYXR","vueuse-functions","Apply VueUse composables where appropriate to build concise, maintainable Vue.js \u002F Nuxt features.","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fvueuse\u002Fvueuse-functions\u002FSKILL.md",[147],{"categoryNo":148,"categoryName":149,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",[151,152,153,154,155,156,157,158],"functions","vueuse functions","js","vue","https","nuxt","build","github",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":169,"publishedAt":47},"01M6CFS34MDQXZPAWQFE5D7VGT","vue-testing-best-practices","Use for Vue.js testing. Covers Vitest, Vue Test Utils, component testing, mocking, testing patterns, and Playwright for E2E testing.","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fvuejs-ai\u002Fvue-testing-best-practices\u002FSKILL.md",[165,168],{"categoryNo":166,"categoryName":167,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":148,"categoryName":149,"taxonomyType":21,"taxonomyTypeDesc":22},[170,154,171,172,173,174,175,176,177,178,158,179,180,181,153],"best practices","testing best practices","testing","vue testing best practices","e2e testing","playwright","test","testing patterns","component","vitest","e2e","use",{"skillNo":183,"name":184,"nameZh":6,"description":185,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":186,"categories":187,"keywords":189,"publishedAt":47},"01M6CFS0N19MSJNTVM9AEQ7Z73","vue-router-best-practices","Vue Router 4 patterns, navigation guards, route params, and route-component lifecycle interactions.","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fvuejs-ai\u002Fvue-router-best-practices\u002FSKILL.md",[188],{"categoryNo":148,"categoryName":149,"taxonomyType":21,"taxonomyTypeDesc":22},[190,170,154,191,158,178,192,193],"vue router best practices","router","navigation","lifecycle",{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":201,"publishedAt":47},"01M6CFRYN31RFQFTE41Z6DCGKE","vue-pinia-best-practices","Pinia stores, state management patterns, store setup, and reactivity with stores.","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fvuejs-ai\u002Fvue-pinia-best-practices\u002FSKILL.md",[200],{"categoryNo":148,"categoryName":149,"taxonomyType":21,"taxonomyTypeDesc":22},[170,154,202,203,204,205,158,206,207],"vue pinia best practices","pinia","state","state management","management","setup",{"skillNo":209,"name":210,"nameZh":6,"description":211,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":212,"categories":213,"keywords":223,"publishedAt":47},"01M6CFRW2DKXJHP05DYJ3P3Y2S","vue-options-api-best-practices","Vue 3 Options API style (data(), methods, this context). Each reference shows Options API solution only.","https:\u002F\u002Fgithub.com\u002Frockcookies\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fvuejs-ai\u002Fvue-options-api-best-practices\u002FSKILL.md",[214,215,218],{"categoryNo":148,"categoryName":149,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":216,"categoryName":217,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":219,"categoryName":220,"taxonomyType":221,"taxonomyTypeDesc":222},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[154,170,224,225,226,227,228,158,229,230],"vue options api best practices","api","only","data","reference","methods","context"]