[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7592CPYX4FK0VDF28YWRZMX":3,"skill-same:01M7592CPYX4FK0VDF28YWRZMX":89},{"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":46,"commitSha":47,"skillDirectory":48,"forksCount":49,"repositoryHtmlUrl":50,"repositoryHomepageUrl":6,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":52,"updatedAt":53,"install":54,"resources":66},"01M7592CPYX4FK0VDF28YWRZMX","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).","davidcoachdev\u002Fdcfiles","davidcoachdev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F69812733?v=4","01M758C4BR16TAV1N47W319E9V","David H. Caycedo Blum.","01M758C4CCZA2ZYGA0BGMXCDRH",1,"MIT","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: golang-refactoring\ndescription: \"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).\"\nuser-invocable: true\nlicense: MIT\ncompatibility: Designed for OpenCode or similar AI coding agents, and for projects using Golang. Requires gopls and git.\nmetadata:\n  author: gentleman-programming\n  version: \"1.0.0\"\n  openclaw:\n    emoji: \"♻️\"\n    homepage: https:\u002F\u002Fgithub.com\u002Fgentleman-programming\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\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:** Use `ultrathink` 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 — a wrong ordering call surfaces as a broken build or a conflict-riddled merge, not as an obviously wrong plan.\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**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:** Use `ultrathink` 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 — a wrong ordering call surfaces as a broken build or a conflict-riddled merge, not as an obviously wrong plan.\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**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,"license":15,"metadata":24,"description":7,"allowed-tools":43,"compatibility":44,"user-invocable":45},{"author":25,"version":26,"openclaw":27},"gentleman-programming","1.0.0",{"emoji":28,"install":29,"homepage":39,"requires":40,"skill-library-version":42},"♻️",[30,35],{"bins":31,"kind":33,"package":34},[32],"gopls","go","golang.org\u002Fx\u002Ftools\u002Fgopls@latest",{"bins":36,"kind":33,"package":38},[37],"benchstat","golang.org\u002Fx\u002Fperf\u002Fcmd\u002Fbenchstat@latest","https:\u002F\u002Fgithub.com\u002Fgentleman-programming",{"bins":41},[33,32],"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 OpenCode or similar AI coding agents, and for projects using Golang. Requires gopls and git.",true,"main","5dc86f90a5cbe45db3acd917825461b3ed6937fb","config\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring",0,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev","🌐 Apasionado por crear soluciones web escalables y eficientes. \r\n🧑‍🏫 Coach Dev.\r\n💻 Frontend Dev. \r\n🎚️Backend Dev.\r\n📊 Agile\u002FScrum.\r\n🚀100% remoto.","2026-08-26 07:28:05",{"source":8,"skillName":5,"commands":55,"prompt":65,"zipAvailable":45},[56,59,62],{"tool":57,"command":58},"npx","npx skills add davidcoachdev\u002Fdcfiles --skill golang-refactoring",{"tool":60,"command":61},"bunx","bunx skills add davidcoachdev\u002Fdcfiles --skill golang-refactoring",{"tool":63,"command":64},"pnpm","pnpm dlx skills add davidcoachdev\u002Fdcfiles --skill golang-refactoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002FSKILL.md",[67,73,77,81,85],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Fcatalog.md","REFERENCE","参考文档",19942,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fcatalog.md",{"path":74,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fgo-tooling.md",8013,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fgo-tooling.md",{"path":78,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Fsafety-net.md",10184,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fsafety-net.md",{"path":82,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":83,"sourceHtmlUrl":84},"references\u002Fstructural.md",16817,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fstructural.md",{"path":86,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Fworkflow.md",18470,"https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fgolang-refactoring\u002Freferences\u002Fworkflow.md",[90,98,105,112,119,126],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":94,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M7740FETMZY1VTYAEFY1TWY7","zustand-5","Zustand 5 state management patterns. Trigger: When managing React state with Zustand.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fzustand-5\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":94,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":19},"01M773ZZM9V68SA1AKP4WF4J29","zod-4","Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fzod-4\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":94,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":19},"01M773ZJFR90CQAY0N9QR40QVP","x-bookmark-quote-posts","Workflow para revisar bookmarks de X\u002FTwitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fx-bookmark-quote-posts\u002FSKILL.md",[],[],{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":19},"01M773Z2RGV3786FV310SDB0YD","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[],[],{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":125,"publishedAt":19},"01M773YJH3KDSW467CSS63CSRJ","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":94,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":19},"01M773Y3S3H2CPRK5S8YFHWB5C","work-unit-commits","Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.","https:\u002F\u002Fgithub.com\u002Fdavidcoachdev\u002Fdcfiles\u002Fblob\u002Fmain\u002Fconfig\u002F.config\u002Fopencode\u002Fskills\u002Fwork-unit-commits\u002FSKILL.md",[],[]]