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/v2.{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 a page under docs/reference/tools/ owns the domain (docs/reference/tools/doc-ownership.json maps tool-name prefixes to pages), read it for supplementary user-facing context — but do NOT skip the move if no doc exists