gitlab-mcp-server: Skill for Claude Code

Go Safe Move Refactor

Primary Directive

Move one or more Go source files from one package to another while maintaining compilation at every intermediate step. This skill implements the "bridge pattern" — keep old code working via forwarding stubs while new code is established, then remove bridges after verification.

When to Use

• Moving a .go file from one package to another
• Extracting a set of functions/types into a new package
• Consolidating multiple files into a single sub-package
• Splitting a large package into smaller ones

Core Principle: Never Break Compilation

Every change must be an atomic step that leaves go build ./... passing. The sequence is:

1. Create destination → 2. Copy & transform → 3. Add forwarding stubs → 4. Verify → 5. Update consumers → 6. Remove stubs → 7. Verify

Process

Step 1: Pre-Flight Check

go build ./...    # Must pass
golangci-lint run --build-tags e2e ./... # Must pass
go test ./...     # Record baseline (should pass)

Record:

• Source file path: ${srcFile} (e.g., internal/tools/branches.go)
• Source package: ${srcPkg} (e.g., tools)
• Destination directory: ${dstDir} (e.g., internal/tools/branches/)
• Destination package: ${dstPkg} (e.g., branches)

Discovery check (before any move): The client-go API defines the canonical domain structure. Verify you have the complete picture:

1. Inspect client-go types: Run go doc gitlab.com/gitlab-org/api/client-go/v3.{Type} for the domain's key types to understand the canonical fields and API contract
2. List all non-test handler files in the source package to find everything that exists
3. Check action_specs.go and catalog aggregation for the domain's canonical runtime exposure
4. Look for related files (e.g., a domain might span {domain}.go + {domain}_extra.go)
5. If the domain's catalog group has a generated tool reference page (site/src/content/docs/reference/tools/<group>.mdx, written by make gen-tool-reference; <group> is the group's tool name without gitlab_ and with hyphens, so gitlab_merge_request is merge-request.mdx), read it for supplementary user-facing context, but do NOT skip the move if there is none. A move never edits that page: it changes only if the move changes what the catalog serves (a tool name, an action ID, a description, a tier or a schema), and then make gen-tool-reference rewrites it