go-troubleshooting

Diagnose Go bugs systematically using reproduction, profiling, race detection, and root-cause analysis.

1|2|Updated Nov 25, 2017
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill go-troubleshooting-asarchami
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: go-troubleshooting
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/go/go-troubleshooting
Command: npx skills add https://github.com/asarchami/dotfiles --skill go-troubleshooting-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Go bugs like nil dereferences, race conditions, goroutine leaks, and silent error swallowing are hard to track down without a disciplined process. This Skill enforces a diagnose-first methodology so you find the root cause instead of patching symptoms. ## Core Features & Use Cases - Systematic Debugging Workflow: A step-by-step loop of reading errors, reproducing with failing tests, measuring one variable at a time, and tracing to the root cause. - Symptom-Based Decision Tree: Routes crashes, hangs, high CPU, memory growth, and flaky behavior to the right tool (pprof, Delve, race detector, GODEBUG). - Go Pitfall Catalog: Detailed references covering nil/interface gotchas, defer traps, context misuse, concurrent map access, JSON surprises, and code review red flags. - Use Case: When a production Go service intermittently deadlocks, use this Skill to capture a goroutine dump via pprof, identify the circular wait, write a failing test, and fix the lock ordering at the source. ## Quick Start Ask the AI to diagnose a reported Go bug, crash, deadlock, or race condition using the go-troubleshooting methodology before proposing any fix.

Frequently Asked Questions about go-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a Go program that randomly crashes or panics?

Run with GOTRACEBACK=all to get full stack traces and execute go test -race ./... to detect data races. Then write a failing test that reproduces the panic deterministically before attempting any fix.

How to find goroutine leaks in a Go application?

Capture a goroutine profile with curl localhost:6060/debug/pprof/goroutine?debug=2 and look for goroutines stuck in chan receive. In tests, use go.uber.org/goleak to automatically detect leaked goroutines.

Why does my Go interface comparison to nil fail?

A typed nil pointer stored in an interface is not a nil interface, so err != nil evaluates true even when the underlying pointer is nil. Fix it by returning an explicit nil instead of a typed nil variable from functions.

Does the Go race detector work in production?

The -race flag slows code roughly 10x, so it is intended for tests and CI rather than production. For live systems, use pprof goroutine and mutex profiles plus structured logging to diagnose concurrency issues.

When should I use Delve versus pprof for Go debugging?

Use Delve for interactive breakpoint debugging of specific code paths in development or tests. Use pprof for production-safe profiling of CPU, heap, goroutines, and lock contention on running services.