go-concurrency-review
Review Go code for concurrency safety and goroutine lifecycle issues including race conditions, deadlocks, goroutine leaks, mutex misuse, and context propagation. Trigger when code contains go func, channels, sync primitives, WaitGroup, errgroup, or goroutine lifecycle management. Use for concurrency-focused review of Go projects.
johnqtcg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add johnqtcg/awesome-skills --skill go-concurrency-reviewAbout this skill
name: go-concurrency-review description: Review Go code for concurrency safety and goroutine lifecycle issues including race conditions, deadlocks, goroutine leaks, mutex misuse, and context propagation. Trigger when code contains go func, channels, sync primitives, WaitGroup, errgroup, or goroutine lifecycle management. Use for concurrency-focused review of Go projects. allowed-tools: Read, Grep, Glob, Bash(go build*), Bash(go vet*), Bash(go test -race*)
Go Concurrency Review
Purpose
Identify concurrency defects and goroutine lifecycle issues in Go code. Scope: race conditions, deadlocks, goroutine leaks, mutex misuse, context propagation, and lifecycle management.
This skill does NOT cover: security vulnerabilities, performance optimization, code style, test quality, error handling patterns, or business logic — those belong to sibling vertical skills.
When To Use
- Code contains
go func, goroutine creation - Code uses channels,
syncprimitives (Mutex, RWMutex, WaitGroup) - Code uses
errgroup,singleflight - Code involves context propagation and cancellation
- Code contains graceful shutdown logic
When NOT To Use
- Security vulnerabilities →
go-security-review - Performance optimization (lock contention as perf issue) →
go-performance-review - Code style/lint →
go-quality-review - Error handling correctness →
go-error-review - Business logic →
go-logic-review
Mandatory Gates
1) Execution Integrity Gate
Never claim go test -race ran unless it actually produced output. If not run: state reason + exact command.
2) Go Version Gate
Read go.mod for go directive. Key version gates:
errgroup.SetLimit(Go 1.20+)sync.OnceValue/sync.OnceFunc(Go 1.21+)- Loop variable fix (Go 1.22+) — do NOT flag loop variable capture in Go ≥ 1.22
3) Anti-Example Suppression Gate
MUST quote specific code evidence satisfying precondition. Category match alone insufficient.
Embedded anti-examples:
- "Race condition on this map" — when map is created and consumed within single function scope or single goroutine. Cite the creation site and all access sites to confirm single-goroutine usage.
- "Should use errgroup instead of WaitGroup" — when no error propagation is needed and goroutine count is small and fixed (e.g., 2-3 known goroutines).
- "Missing context propagation" — when function is synchronous, short-lived, performs no I/O, and has no cancellable work.
- "Loop variable capture bug" — when project uses Go ≥ 1.22 (check go.mod). The loop variable fix makes
v := vunnecessary. - "Should add mutex" — when data structure is only written during initialization (before any goroutine launch) and only read afterward.
4) Generated Code Exclusion Gate
Exclude: *.pb.go, *_gen.go, mock_*.go. Note excluded files in Execution Status.
Workflow
- Define scope — files/diff under review. Apply Generated Code Exclusion Gate.
- Gather evidence — read changed files, identify concurrency patterns:
go func,chan,sync.*,errgroup,context.WithCancel,select,time.After. - Load references — always load
go-concurrency-patterns.md. - Run
go test -raceif feasible — report output. If not feasible, state reason + exact command. - Evaluate ALL 14 checklist items → apply suppression gate → format output.
Grep-Gated Execution Protocol
This skill uses mechanical grep pre-scanning to guarantee zero missed checklist items. 13 of 14 items are grep-gated; 1 is semantic-only.
Execution Order
- Identify target files (from dispatch prompt, or write raw snippet to
$TMPDIR/review_snippet.go) - Run grep for all grep-gated checklist items against target files
- HIT → run semantic analysis to confirm or reject
- MISS → auto-mark NOT FOUND, skip semantic analysis
- For compound patterns: run all grep patterns, apply AND/AND NOT logic
- For semantic-only items (item 13): full model reasoning
- Report only FOUND items
Grep Audit Line
Include in Execution Status: Grep pre-scan: X/13 items hit, Z confirmed as findings (1 semantic-only)
Compound Pattern Protocol
Several items share the trigger go\s+func but have different secondary conditions:
- Item 8 (Unrecovered panic):
go\s+funcHIT ANDrecover()NOT found in goroutine body - Item 12 (Loop variable capture):
go\s+funcHIT AND insideforloop AND Go version < 1.22 - Item 14 (Unbounded goroutines):
go\s+funcHIT AND NONE ofSetLimit|semaphore|maxConcurrency|worker.*pool|make(chan structfound in same scope
Run go\s+func grep ONCE, then apply all compound conditions to the results.
Concurrency Checklist (14 Items)
All High severity unless marked (Medium).
| # | Item | Code Pattern Triggers | Grep Pattern |
|---|---|---|---|
| 1 | Goroutine leak | go func without context cancel or channel close on return path | go\s+func|go\s+\w+\( |
| 2 | Data race | Shared map/slice/var written from multiple goroutines without sync | go\s+func (compound: ALSO check shared variable write in closure — semantic confirmation required) |
| 3 | Mutex misuse | Missing defer mu.Unlock(), lock copying (value receiver on mutex-holding struct), inconsistent RWMutex | sync\.Mutex|sync\.RWMutex |
| 4 | Channel deadlock | Unbuffered send without receiver, missing close(), select without default on full channel | make\(chan|<-chan|chan<-|<-\s*\w+ |
| 5 | Missing errgroup | Multiple goroutines coordinated without error propagation — should use errgroup.Group | sync\.WaitGroup|wg\. |
| 6 | Missing context propagation | context.Background() where parent ctx available; context.Value for request-scoped data | context\.Background\(\)|context\.TODO\(\)|context\.Value |
| 7 | sync.Pool / sync.Once misuse | Pool without Reset before Put; Once panic caching (Go < 1.21, use OnceValue after) | sync\.Pool|sync\.Once |
| 8 | **Unrecov |