---
name: go-package-debugger
description: "A root-cause diagnosis for a Go package that will not compile, panics, or misbehaves: the likely cause ranked by evidence, the fix with before-and-after code, and the go build, vet, and test commands that prove it. Use when a Go package fails to compile, panics with a stack trace, deadlocks, or fails the race detector and the user needs the root cause and the fix. Do not use for general Go code review or performance profiling of code that already works. Related topics: coding, package."
---

# Go Package Debugger

A root-cause diagnosis for a Go package that will not compile, panics, or misbehaves: the likely cause ranked by evidence, the fix with before-and-after code, and the go build, vet, and test commands that prove it.

## When to use

Use this skill when a Go package fails to compile, panics with a stack trace, deadlocks, or fails the race detector and the user needs the root cause and the fix. Do not use it for general Go code review or performance profiling of code that already works.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Extract the failing file, line, and frame from the compiler output or stack trace before reading the code, so the diagnosis starts where the runtime says.
3. Classify the failure and name the most likely root cause with its supporting evidence, plus one alternative when the evidence is ambiguous.
4. Write the fix as a before-and-after code change that keeps Go idioms: errors returned, no recover to hide bugs, no sleeps around races.
5. List the go build, go vet, and go test commands that prove the fix, with the -race flag for concurrency bugs and the expected output.
6. Add the test snippet that would have caught the bug when test commands are requested, and trim the write-up to the chosen level of detail.

## Inputs

- **Package import path** (free text, e.g. "github.com/acme/app/internal/billing")
- **Go version** (choose one: 1.21, 1.22, 1.23, 1.24)
- **Target OS and architecture** (choose one: linux/amd64, linux/arm64, darwin/arm64, windows/amd64)
- **Observed symptom** (choose one: Compile error, Panic at runtime, Wrong output, Hangs or deadlocks, Race detector report, Test failure)
- **Error output** (longer free text)
- **Relevant code** (longer free text)
- **What you expected** (free text, e.g. "One sentence")
- **Level of detail** (choose one: Brief, Moderate, Thorough)
- **Include test command snippets** (choose one: Yes, No)

## Output

A markdown report with sections Summary, Root cause (with evidence), Fix (before and after code), Verify (commands and expected output), and Prevent (one or two lines), sized to the selected detail level.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Go Package Debugger

Diagnose why my Go package fails and tell me exactly how to fix it.

#### Details
- Package import path: {{Package import path}}
- Go version: {{Go version}}
- Target OS and architecture: {{Target OS and architecture}}
- Observed symptom: {{Observed symptom}}
- Error output: {{Error output}}
- Relevant code: {{Relevant code}}
- What you expected: {{What you expected}}
- Level of detail: {{Level of detail}}
- Include test command snippets: {{Include test command snippets}}

Read the error output before the code: the compiler names the file and line, and a panic's stack trace points at the goroutine and frame where it started, not where the bug was written. Classify the failure (type or import error, nil pointer, index out of range, unhandled error, data race, deadlock, build tag or platform mismatch) and name the single most likely cause with the evidence that supports it, then one alternative if the evidence is ambiguous. Give the fix as a code change with before and after, keeping Go idioms: errors returned and checked, no recover used to hide a bug, no sleeps to paper over a race. State how to confirm the fix with go build, go vet, and go test (with -race for concurrency bugs) and what each should print. Match the depth to the selected level: brief is the cause and the fix only.

## Pitfalls

- Blaming the line that panicked when the nil was created several frames earlier, which fixes a symptom and leaves the bug.
- Wrapping the crash in recover or adding a nil check without finding why the value was nil.
- Ignoring GOOS and GOARCH, so a build-tag or cgo problem that only shows on the target platform is missed.
