ALWAYS load when browsing or editing go project. Use this skill whenever you need to read, navigate, explore, or modify Go source code in a project that has `go-surgeon` installed (check for the binary or `go-surgeon` in go.mod). This includes adding, updating, or deleting functions, methods, structs, and interfaces; generating mocks; implementing interface stubs; generating test skeletons; manipulating struct tags; extracting interfaces from structs; and exploring codebase structure. Trigger this skill for ANY Go code editing task — even simple ones like "add a method" or "rename this function" — because go-surgeon produces deterministic, AST-correct results that avoid indentation errors, import issues, and context window waste. Also trigger when the user says "explore the codebase", "find symbol X", "show me the function", "list packages", or wants to understand Go project structure. Do NOT use generic text tools (cat, sed, grep, diff) for Go code editing when go-surgeon is available.
You are editing Go code in a project that has go-surgeon available. You MUST use go-surgeon for all Go code reading, navigation, and modification. Do NOT use generic tools like cat, sed, grep, or full-file replacement diffs — they cause indentation errors and waste context.
go-surgeon is a deterministic AST-based byte-range editor. It automatically runs goimports on every mutation, so you NEVER need to manage imports or formatting.
Always start by exploring the codebase structure rather than reading full files.
go-surgeon graph
go-surgeon graph --symbols --dir <relative_dir>
# Short: go-surgeon graph -s -d <relative_dir>
Additional flags:
--summary: Include package doc comment summary--deps: Show internal import dependencies--tests: Include _test.go files--recursive=false: Only the target directory (no sub-packages), used with --symbolsUse these to avoid overwhelming the token budget on large codebases:
# Limit directory recursion depth (1 = target dir only, 2 = immediate children)
go-surgeon graph --summary --depth 2
# Full detail for one package, path-only for the rest (implies --symbols --summary -r)
go-surgeon graph --focus internal/catalog/domain
# Skip directories matching glob patterns (repeatable)
go-surgeon graph --exclude vendor --exclude "*legacy*"
# Progressive truncation to fit approximate token count
# Strips in order: summaries → deps → symbols → files → package list
go-surgeon graph --summary --deps --token-budget 2000
For large codebases, zoom in step by step:
go-surgeon graph --summary --depth 2 — high-level mapgo-surgeon graph --focus <package> — full detail on the interesting areago-surgeon graph -s -d <subdir> — symbols in one subtree# Free function or struct
go-surgeon symbol NewBook
# Method on a receiver (Receiver.Method form)
go-surgeon symbol BookHandler.Handle
# With full body (empty lines stripped to save tokens)
go-surgeon symbol NewBook --body
# Scoped to a directory
go-surgeon symbol Validate --dir internal/catalog/domain
# Short: go-surgeon symbol Validate -b -d internal/catalog/domain
Important: Use Receiver.Method form for precise method lookups. If multiple matches are found, a disambiguation index is returned — refine with Receiver.Method or --dir.
NEVER use cat <<'EOF' | go-surgeon ... heredoc pipes — they trigger permission prompts. Instead, write YAML plan files to .tmp/ and execute them with go-surgeon execute -f.
Write one or more actions to a .tmp/plan_name.yaml file using the Write tool, then execute:
go-surgeon execute -f .tmp/plan_name.yaml
Plans are auto-deleted on success. You can batch multiple actions and run multiple plans in one call:
go-surgeon execute -f .tmp/plan_a.yaml -f .tmp/plan_b.yaml
Plan file schema: