Golang Troubleshooting
Debug flaky or failing Go services using golden rules: reproduce with a failing test first, then change one hypothesis at a time.
Overview
golang-troubleshooting is an agent skill most often used in Ship (also Build backend, Operate errors) that enforces test-first, hypothesis-driven Go debugging.
Install
npx skills add https://github.com/samber/cc-skills-golang --skill golang-troubleshootingWhat is this skill?
- Enforces failing-test-first reproduction before proposing handler or service fixes
- Pushes one-hypothesis-at-a-time changes instead of shotgun patches
- Covers HTTP handlers, JSON decode paths, and intermittent 500-class failures
- Expects clarifying questions on logs, bodies, and frequency before guessing
- Aligns agent behavior with eval traps for disciplined Go incident response
- Golden Rule #2: failing test before any fix
- Golden Rule #4: one hypothesis change at a time
Adoption & trust: 3.7k installs on skills.sh; 2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Go service fails or slows intermittently and the agent keeps suggesting multi-file fixes without a reproducing test or clear evidence.
Who is it for?
Indie Go backend authors debugging HTTP handlers, JSON APIs, DB latency, and flaky tests before ship or during incidents.
Skip if: Greenfield feature generation with no failing behavior, or non-Go stacks where the golden-rule traps do not apply.
When should I use this skill?
Go tests fail, handlers return intermittent errors, or performance regresses and you need systematic reproduction instead of speculative patches.
What do I get? / Deliverables
You get a failing test that captures the bug, a single validated hypothesis change, and a fix backed by measured before/after behavior.
- Failing reproduction test
- Root-cause hypothesis with evidence
- Minimal verified fix
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship/testing is the canonical shelf because the skill centers on evidence-led debugging and test-first reproduction before release-quality fixes. Testing subphase matches writing failing tests, isolating inputs, and validating fixes—not greenfield feature coding.
Where it fits
A JSON order handler regresses after a schema change—write table-driven tests that expose which bodies trigger 500 before patching decode logic.
Pre-release, stabilize flaky integration tests around `processOrder` by reproducing failures and changing one variable per run.
Users report sporadic errors—collect logs and request samples, add a failing test mirroring prod input, then apply a single measured fix.
How it compares
Methodology skill for Go incident discipline—not a log aggregator, profiler SaaS, or generic linter.
Common Questions / FAQ
Who is golang-troubleshooting for?
Solo builders maintaining Go APIs and services who want their agent to debug with tests and evidence instead of guesswork.
When should I use golang-troubleshooting?
Use it in Ship while hardening tests pre-release, in Build when backend regressions appear, and in Operate when triaging 500s, slowness, or ambiguous handler errors.
Is golang-troubleshooting safe to install?
Review the Security Audits panel on Prism and the samber/cc-skills-golang source; the skill guides reasoning and tests and should not require secrets beyond normal local dev access.
SKILL.md
READMESKILL.md - Golang Troubleshooting
[ { "id": 1, "name": "reproduce-before-fix-failing-test-first", "description": "Tests Golden Rule #2: model must write a failing test before proposing any fix, not jump to code changes", "prompt": "My Go HTTP handler returns 500 for some requests but I can't figure out which ones. The handler parses a JSON body with `json.NewDecoder(r.Body).Decode(&req)` and then calls `processOrder(req)`. Some users report getting 500 errors. Can you fix this?", "trap": "Model jumps directly to adding nil checks or error handling in the handler code without first writing a test that reproduces the failure", "assertions": [ {"id": "1.1", "text": "Writes a failing test (or proposes writing one) BEFORE suggesting any code fix"}, {"id": "1.2", "text": "Test covers multiple input variations to identify which inputs trigger the 500"}, {"id": "1.3", "text": "Does NOT propose a fix without first understanding/reproducing the root cause"}, {"id": "1.4", "text": "Asks clarifying questions about the error (logs, request bodies, frequency) or proposes to gather evidence"}, {"id": "1.5", "text": "Mentions running the test to confirm it reproduces the issue before fixing"} ] }, { "id": 2, "name": "one-hypothesis-at-a-time", "description": "Tests Golden Rule #4: change one thing and measure, not multiple simultaneous changes", "prompt": "My Go web service is slow and sometimes returns errors. I think it might be the database queries, or maybe the JSON marshaling, or possibly goroutine contention. Can you fix all three at once to save time? Add connection pooling, switch to a faster JSON library, and add mutexes around shared state.", "trap": "Model applies all three fixes simultaneously as requested, violating the one-hypothesis-at-a-time rule", "assertions": [ {"id": "2.1", "text": "Refuses or strongly advises against making all three changes simultaneously"}, {"id": "2.2", "text": "Recommends measuring/profiling first to identify which problem is actually causing the symptoms"}, {"id": "2.3", "text": "Suggests testing one hypothesis at a time with measurement between changes"}, {"id": "2.4", "text": "Mentions pprof, benchmarks, or race detector as diagnostic tools to identify the real bottleneck"}, {"id": "2.5", "text": "Explains why multiple simultaneous changes are harmful (can't tell what worked, may introduce new bugs)"} ] }, { "id": 3, "name": "root-cause-not-symptom-fix", "description": "Tests Golden Rule #5 and Step 8: fix at the source where bad data originates, not where the panic occurs", "prompt": "My Go HTTP server panics with `nil pointer dereference` in the handler when accessing `s.db.Query(...)`. I added a nil check `if s.db == nil { return }` but now the handler silently returns empty responses. How do I fix this properly?", "trap": "Model suggests improving the nil check (better error message, logging) rather than tracing to the root cause — why is s.db nil in the first place", "assertions": [ {"id": "3.1", "text": "Identifies that the nil check in the handler is a symptom fix, not the root cause"}, {"id": "3.2", "text": "Traces backward to the constructor/initialization code to find why db is nil"}, {"id": "3.3", "text": "Suggests validating db != nil in the constructor (e.g., NewServer) and failing fast there"}, {"id": "3.4", "text": "Does NOT suggest improving the nil check in the handler as the primary fix"}, {"id": "3.5", "text": "Explains that fixing at the symptom location masks the real bug"} ] }, { "id": 4, "name": "interface-nil-gotcha", "description": "Tests the interface nil gotcha from common-go-bugs: typed nil in interface is not nil", "prompt": "I have this Go code and the error branch always executes even though no error occurred. Debug this:\n\n```go\ntype ValidationError struct{ Field string }\nfunc (e *ValidationError)