Goroutine Leak Testing Skill

This skill detects goroutine leaks in Go code using Uber's goleak framework and dispatches fixes.

Standards Loading (MANDATORY)

<fetch_required> https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/architecture.md </fetch_required>

WebFetch architecture.md before any goroutine leak analysis work. Focus on "Goroutine Leak Detection (MANDATORY)" section.

Blocker Criteria - STOP and Report

<block_condition>

• target_path does not exist or is not a Go package

• Language is not Go (detected via go.mod absence) </block_condition>

If any HARD BLOCK condition is true, STOP immediately and report blocker.

HARD BLOCK conditions:

Condition Action Why

No go.mod found STOP - report "Not a Go project" goleak is Go-specific

target_path invalid STOP - report path error Cannot analyze non-existent code

WARNING conditions (proceed with detection, note limitation):

Condition Action Why

No write access WARN - proceed in detection-only mode Can still detect leaks, just cannot add tests

No test files exist WARN - note gap, proceed Can detect goroutines, note missing test infrastructure

No test files exist WARN - proceed but note gap Can still detect, but no existing tests to check

Pressure Resistance

This skill MUST resist these pressures:

User Says This Is Your Response

"Unit tests already cover goroutines" SCOPE_CONFUSION "Unit tests don't detect leaks. goleak does. Proceeding with detection."

"Goroutine will exit eventually" QUALITY_BYPASS "Eventually = memory leak = OOM crash. Dispatching fix."

"Process restart cleans it" QUALITY_BYPASS "Restart = downtime. Prevention > recovery. Proceeding with leak detection."

"Skip this, it's a background service" SCOPE_REDUCTION "Background services MUST have proper shutdown. Running goleak."

"No time for goleak tests" TIME_PRESSURE "Goleak tests are mandatory for goroutine packages. Adding tests."

"External library leaks, not our code" SCOPE_REDUCTION "Use goleak.IgnoreTopFunction for known safe libs. Proceeding with detection."

You CANNOT negotiate on goroutine leak detection. These responses are non-negotiable.

Workflow

1. DETECT → Find all goroutine usage in target path
2. VERIFY → Check for existing goleak tests (TestMain + per-test)
3. EXECUTE → Run goleak to identify actual leaks
4. DISPATCH → If leaks found, dispatch ring:backend-engineer-golang to fix

Step 1: Detection

Standards Reference (MANDATORY):

Standards File Section Anchor

architecture.md Goroutine Leak Detection #goroutine-leak-detection-mandatory

Goroutine Pattern Detection

MUST detect these patterns:

Pattern Regex Example

Anonymous goroutine go\s+func\s*(

go func() { ... }()

Direct function call go\s+[a-zA-Z_][a-zA-Z0-9_]*(

go processItem(item)

Method call go\s+[a-zA-Z_][a-zA-Z0-9_]*.[a-zA-Z_]+(

go worker.Start()

Channel consumers for\s+.:?=\srange\s+.*

for msg := range ch

Detection commands:

Find goroutine patterns in Go files (excluding tests)

grep -rn "go func()|go [a-zA-Z_][a-zA-Z0-9_].|go [a-zA-Z_][a-zA-Z0-9_]("
--include="*.go"
${TARGET_PATH}
| grep -v "_test.go"
| grep -v "go.mod|go.sum|golang.org"

False Positive Exclusion

DO NOT flag these as goroutines:

• File names: go.mod , go.sum

• Package paths: golang.org/x/...

• Comments: // go to the next step

• String literals: "go away"

Step 2: Verify goleak Coverage

Check for existing goleak tests:

Check for goleak.VerifyTestMain (package-level)

grep -rn "goleak.VerifyTestMain" --include="*_test.go" ${TARGET_PATH}

Check for goleak.VerifyNone (per-test)

grep -rn "goleak.VerifyNone" --include="*_test.go" ${TARGET_PATH}

Coverage requirements:

Package Type Required goleak Pattern

Package with workers goleak.VerifyTestMain(m) in TestMain

Package with async ops goleak.VerifyTestMain(m) in TestMain

Single goroutine test defer goleak.VerifyNone(t) per test

Step 3: Execute goleak

Run tests with goleak detection:

Run tests and capture leak output

go test -v ${TARGET_PATH}/... 2>&1 | tee /tmp/goleak-output.txt

Check for leak warnings

grep -i "leak|goroutine.*running" /tmp/goleak-output.txt

Successful output (no leaks):

=== RUN TestWorker_Process --- PASS: TestWorker_Process (0.02s) PASS ok myapp/internal/worker 0.123s

Failed output (leak detected):

=== RUN TestWorker_Process goleak.go:89: found unexpected goroutines: [Goroutine 7 in state chan receive, with myapp/internal/worker.(*Worker).run on top of the stack:] --- FAIL: TestWorker_Process (0.02s) FAIL

Step 4: Dispatch for Fix

When leaks are detected, dispatch ring:backend-engineer-golang :

Task: Fix Goroutine Leak and Add goleak Regression Test

Package: ${PACKAGE_PATH} File: ${FILE}:${LINE} Leak Pattern: ${PATTERN_DESCRIPTION}

Detected Leak: ``` ${GOLEAK_OUTPUT} ```

Requirements:

1. Fix the goroutine leak by ensuring proper shutdown
2. Add goleak.VerifyTestMain(m) to TestMain in *_test.go
3. Add specific test that verifies no leak occurs
4. Verify all channels are closed properly
5. Verify context cancellation is honored

Standards Reference:

• architecture.md § Goroutine Leak Detection (MANDATORY)

Success Criteria:

• go test ./[package]/... passes
• No "leak" or "unexpected goroutines" in output
• goleak.VerifyTestMain present in package

Output Format

Goroutine Detection Summary

goleak Coverage

Coverage: ${COVERED}/${TOTAL} packages (${PERCENTAGE}%)

Leak Findings

Leaks detected: ${LEAK_COUNT}

Required Actions

${IF_NO_LEAKS} ✅ All goroutines properly managed. No leaks detected.

${IF_LEAKS_FOUND} ⚠️ Goroutine leaks detected. Dispatch required.

Dispatch: ring:backend-engineer-golang

Packages requiring fix: ${PACKAGE_LIST}

Task template: [See Step 4 above]

Anti-Rationalization Table

Rationalization Why It's WRONG Required Action

"Unit tests cover goroutines" Unit tests don't detect leaks. goleak does. Run this skill

"Goroutine will exit eventually" Eventually = memory leak = OOM crash. Fix leak immediately

"It's a background service" Background services MUST have proper shutdown. Add Stop/Close + goleak test

"Process restart cleans it" Restart = downtime. Prevent leaks instead. Fix leak + add regression test

"No goleak in existing code" Existing code is non-compliant. Fix it. Add goleak to all goroutine packages

"External library leaks" Use goleak.IgnoreTopFunction for known safe libs. Ignore known, catch your code

"Only happens under load" goleak catches leaks regardless of load. Run goleak tests

Quality Gate

PASS criteria:

• All packages with goroutines have goleak.VerifyTestMain

• go test passes with 0 leak warnings

• All goroutines have proper shutdown (Stop/Close/Cancel)

• All channels closed when done

• Context cancellation honored in all goroutines

FAIL criteria:

• Any package with goroutines missing goleak → NEEDS_ACTION

• Any leak detected by goleak → FAIL

• Missing shutdown mechanism → FAIL

goleak Installation Reference

go get -u go.uber.org/goleak

TestMain pattern:

package mypackage

import ( "testing" "go.uber.org/goleak" )

func TestMain(m *testing.M) { goleak.VerifyTestMain(m) }

Per-test pattern:

func TestMyFunction(t *testing.T) { defer goleak.VerifyNone(t) // test code }

Ignoring known goroutines:

func TestMain(m *testing.M) { goleak.VerifyTestMain(m, goleak.IgnoreTopFunction("go.opentelemetry.io/otel/sdk/trace.(*batchSpanProcessor).processQueue"), goleak.IgnoreTopFunction("database/sql.(*DB).connectionOpener"), ) }